@rathnasgala/cli 0.0.1

package/src/github-credential-store.js

@@ -0,0 +1,65 @@
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export function githubCredentialPath({ platform = process.platform, environment = process.env, home = os.homedir() } = {}) {
+  if (platform === 'win32') {
+    if (!environment.APPDATA) throw new Error('APPDATA is required to store GitHub credentials on Windows');
+    return path.join(environment.APPDATA, 'Gala', 'github-credentials.json');
+  }
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Gala', 'github-credentials.json');
+  return path.join(environment.XDG_CONFIG_HOME || path.join(home, '.config'), 'gala', 'github-credentials.json');
+}
+
+async function regularOrMissing(target) {
+  try {
+    const metadata = await lstat(target);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) throw new TypeError('GitHub credential must be a regular file');
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function writeGithubCredential({ accessToken, scopes, target = githubCredentialPath() }) {
+  if (typeof accessToken !== 'string' || accessToken === '') throw new TypeError('accessToken is required');
+  if (!Array.isArray(scopes) || !scopes.includes('repo') || !scopes.includes('workflow')) {
+    throw new TypeError('GitHub credential requires repo and workflow scopes');
+  }
+  const directory = path.dirname(path.resolve(target));
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const directoryMetadata = await lstat(directory);
+  if (directoryMetadata.isSymbolicLink() || !directoryMetadata.isDirectory()) {
+    throw new TypeError('GitHub credential directory must be a real directory');
+  }
+  await chmod(directory, 0o700);
+  const exists = await regularOrMissing(target);
+  const temporary = `${target}.gala-${process.pid}`;
+  const backup = `${target}.gala-backup-${process.pid}`;
+  try {
+    await writeFile(temporary, `${JSON.stringify({ schemaVersion: 1, accessToken, scopes })}\n`, {
+      flag: 'wx', mode: 0o600
+    });
+    await chmod(temporary, 0o600);
+    if (exists) await rename(target, backup);
+    try { await rename(temporary, target); }
+    catch (error) { if (exists) await rename(backup, target); throw error; }
+    await chmod(target, 0o600);
+    if (exists) await rm(backup);
+    return path.resolve(target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function readGithubCredential({ target = githubCredentialPath() } = {}) {
+  if (!await regularOrMissing(target)) throw new Error('GitHub authentication is missing; run `gala auth github`');
+  const payload = JSON.parse(await readFile(target, 'utf8'));
+  if (payload?.schemaVersion !== 1 || typeof payload.accessToken !== 'string'
+      || !Array.isArray(payload.scopes) || !payload.scopes.includes('repo') || !payload.scopes.includes('workflow')) {
+    throw new TypeError('GitHub credential file has an unsupported schema or missing scopes');
+  }
+  return Object.freeze({ accessToken: payload.accessToken, scopes: [...payload.scopes] });
+}

package/src/github-device-flow.js

@@ -0,0 +1,130 @@
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} is required`);
+  }
+  return value.trim();
+}
+
+function positiveInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${field} must be a positive integer`);
+  }
+  return value;
+}
+
+async function postForm(fetchImpl, url, fields) {
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/x-www-form-urlencoded'
+    },
+    body: new URLSearchParams(fields)
+  });
+  if (!response.ok) {
+    throw new Error(`GitHub OAuth request failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (payload == null || Array.isArray(payload) || typeof payload !== 'object') {
+    throw new TypeError('GitHub OAuth response must be a JSON object');
+  }
+  return payload;
+}
+
+export async function requestDeviceCode({ clientId, scopes, fetchImpl = fetch }) {
+  const normalizedClientId = requiredString(clientId, 'clientId');
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new TypeError('scopes must be a non-empty list');
+  }
+  const normalizedScopes = scopes.map((scope) => requiredString(scope, 'scope'));
+  const payload = await postForm(fetchImpl, DEVICE_CODE_URL, {
+    client_id: normalizedClientId,
+    scope: normalizedScopes.join(' ')
+  });
+
+  return Object.freeze({
+    deviceCode: requiredString(payload.device_code, 'device_code'),
+    userCode: requiredString(payload.user_code, 'user_code'),
+    verificationUri: requiredString(payload.verification_uri, 'verification_uri'),
+    expiresInSeconds: positiveInteger(payload.expires_in, 'expires_in'),
+    intervalSeconds: positiveInteger(payload.interval, 'interval')
+  });
+}
+
+export async function pollForAccessToken({
+  clientId,
+  deviceCode,
+  expiresInSeconds,
+  intervalSeconds,
+  requiredScopes = [],
+  fetchImpl = fetch,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  now = Date.now
+}) {
+  const normalizedClientId = requiredString(clientId, 'clientId');
+  const normalizedDeviceCode = requiredString(deviceCode, 'deviceCode');
+  if (!Array.isArray(requiredScopes)) throw new TypeError('requiredScopes must be a list');
+  const normalizedRequiredScopes = requiredScopes.map((scope) =>
+    requiredString(scope, 'scope').toLowerCase()
+  );
+  const lifetime = positiveInteger(expiresInSeconds, 'expiresInSeconds') * 1000;
+  let interval = positiveInteger(intervalSeconds, 'intervalSeconds');
+  const startedAt = now();
+  if (typeof startedAt !== 'number' || !Number.isFinite(startedAt)) {
+    throw new TypeError('Clock must return epoch milliseconds');
+  }
+
+  while (true) {
+    await sleep(interval * 1000);
+    const currentTime = now();
+    if (typeof currentTime !== 'number' || !Number.isFinite(currentTime)) {
+      throw new TypeError('Clock must return epoch milliseconds');
+    }
+    if (currentTime - startedAt >= lifetime) {
+      throw new Error('GitHub device code expired before authorization completed');
+    }
+
+    const payload = await postForm(fetchImpl, ACCESS_TOKEN_URL, {
+      client_id: normalizedClientId,
+      device_code: normalizedDeviceCode,
+      grant_type: DEVICE_GRANT
+    });
+    if (typeof payload.access_token === 'string' && payload.access_token !== '') {
+      const tokenType = requiredString(payload.token_type, 'token_type');
+      if (tokenType.toLowerCase() !== 'bearer') {
+        throw new TypeError('GitHub OAuth token_type must be bearer');
+      }
+      const grantedScopes = typeof payload.scope === 'string'
+        ? payload.scope.split(/[,\s]+/).map((scope) => scope.trim().toLowerCase()).filter(Boolean)
+        : [];
+      const missingScopes = normalizedRequiredScopes.filter((scope) => !grantedScopes.includes(scope));
+      if (missingScopes.length > 0) {
+        throw new Error(`GitHub authorization omitted required scope(s): ${missingScopes.join(', ')}`);
+      }
+      return Object.freeze({
+        accessToken: requiredString(payload.access_token, 'access_token'),
+        tokenType: 'bearer',
+        scopes: grantedScopes
+      });
+    }
+
+    if (payload.error === 'authorization_pending') continue;
+    if (payload.error === 'slow_down') {
+      interval = Number.isSafeInteger(payload.interval) && payload.interval > interval
+        ? payload.interval
+        : interval + 5;
+      continue;
+    }
+    if (payload.error === 'expired_token' || payload.error === 'token_expired') {
+      throw new Error('GitHub device code expired before authorization completed');
+    }
+    if (typeof payload.error === 'string' && payload.error !== '') {
+      throw new Error(`GitHub device authorization failed: ${payload.error}`);
+    }
+    throw new TypeError('GitHub OAuth response contained neither a token nor an error');
+  }
+}

package/src/github-empty-repository.js

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+
+const API_VERSION = '2026-03-10';
+
+export async function verifyEmptyRepository({ owner, repository, accessToken, fetchImpl = fetch }) {
+  const repositoryUrl = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}`;
+  const headers = {
+    accept: 'application/vnd.github+json', authorization: `Bearer ${accessToken}`,
+    'x-github-api-version': API_VERSION
+  };
+  const response = await fetchImpl(repositoryUrl, {
+    headers
+  });
+  if (!response.ok) throw new Error(`GitHub repository lookup failed with HTTP ${response.status}`);
+  const payload = await response.json();
+  if (payload.full_name?.toLowerCase() !== `${owner}/${repository}`.toLowerCase()) {
+    throw new TypeError('GitHub returned an unexpected repository');
+  }
+  const branchesResponse = await fetchImpl(`${repositoryUrl}/branches?per_page=1`, {
+    headers: {
+      ...headers
+    }
+  });
+  if (!branchesResponse.ok) throw new Error(`GitHub branch lookup failed with HTTP ${branchesResponse.status}`);
+  const branches = await branchesResponse.json();
+  if (payload.size !== 0 || !Array.isArray(branches) || branches.length !== 0) {
+    throw new Error('Existing repository is not empty; explicit non-empty adoption is not implemented');
+  }
+}
+
+export function setRepositoryOrigin({ root, owner, repository, spawnProcess = spawn }) {
+  const target = `https://github.com/${owner}/${repository}.git`;
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, 'remote', 'set-url', 'origin', target], {
+      cwd: root, shell: false, stdio: 'inherit'
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git remote update terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git remote update exited with code ${code}`));
+      else resolve();
+    });
+  });
+}
+
+export function verifyRepositoryOrigin({ root, owner, repository, spawnProcess = spawn }) {
+  const expected = `https://github.com/${owner}/${repository}.git`;
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, 'remote', 'get-url', 'origin'], {
+      cwd: root, shell: false, stdio: ['ignore', 'pipe', 'inherit']
+    });
+    let output = '';
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk) => { output += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git origin verification terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git origin verification exited with code ${code}`));
+      else if (output.trim() !== expected) reject(new Error(`Existing checkout origin must be ${expected}`));
+      else resolve(root);
+    });
+  });
+}

package/src/github-pages-provisioning.js

@@ -0,0 +1,83 @@
+const GITHUB_API_VERSION = '2026-03-10';
+const SEGMENT = /^[A-Za-z0-9_.-]+$/;
+const SHA = /^[0-9a-f]{40}$/;
+
+function required(value, field, pattern = null) {
+  if (typeof value !== 'string' || value.length === 0 || (pattern != null && !pattern.test(value))) {
+    throw new TypeError(`${field} is invalid`);
+  }
+  return value;
+}
+
+function headers(accessToken) {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${accessToken}`,
+    'content-type': 'application/json',
+    'x-github-api-version': GITHUB_API_VERSION
+  };
+}
+
+async function json(response, operation) {
+  if (!response.ok) throw new Error(`GitHub ${operation} failed with HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function provisionGithubPages({
+  owner, repository, accessToken, commitSha, fetchImpl = fetch,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  pollIntervalMs = 5_000, maxPolls = 120
+}) {
+  const normalizedOwner = required(owner, 'owner', SEGMENT);
+  const normalizedRepository = required(repository, 'repository', SEGMENT);
+  const token = required(accessToken, 'accessToken');
+  const sha = required(commitSha, 'commitSha', SHA);
+  if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 0) {
+    throw new TypeError('pollIntervalMs must be a non-negative safe integer');
+  }
+  if (!Number.isSafeInteger(maxPolls) || maxPolls <= 0) {
+    throw new TypeError('maxPolls must be a positive safe integer');
+  }
+  const requestHeaders = headers(token);
+  const repositoryUrl = `https://api.github.com/repos/${encodeURIComponent(normalizedOwner)}/${encodeURIComponent(normalizedRepository)}`;
+  const query = new URLSearchParams({ event: 'push', head_sha: sha, per_page: '10' });
+  let run = null;
+  for (let poll = 0; poll < maxPolls; poll += 1) {
+    const response = await fetchImpl(`${repositoryUrl}/actions/workflows/publish.yml/runs?${query}`, {
+      method: 'GET', headers: requestHeaders
+    });
+    const payload = await json(response, 'publish workflow runs request');
+    run = payload.workflow_runs?.find((candidate) => candidate.head_sha === sha) ?? null;
+    if (run?.status === 'completed') break;
+    if (poll + 1 < maxPolls) await sleep(pollIntervalMs);
+  }
+  if (run == null || run.status !== 'completed') {
+    throw new Error(`Timed out waiting for the publish workflow for ${sha}`);
+  }
+  if (run.conclusion !== 'success') {
+    throw new Error(`Initial publish workflow failed: ${run.html_url}`);
+  }
+  const branch = await fetchImpl(`${repositoryUrl}/branches/gh-pages`, {
+    method: 'GET', headers: requestHeaders
+  });
+  if (!branch.ok) {
+    throw new Error(`Successful publish run created no gh-pages branch: ${run.html_url}`);
+  }
+  const current = await fetchImpl(`${repositoryUrl}/pages`, { method: 'GET', headers: requestHeaders });
+  if (current.ok) {
+    const configuration = await current.json();
+    if (configuration.source?.branch !== 'gh-pages' || configuration.source?.path !== '/') {
+      throw new Error('Existing GitHub Pages configuration does not use gh-pages at /');
+    }
+    return Object.freeze({ created: false, url: configuration.html_url, runUrl: run.html_url });
+  }
+  if (current.status !== 404) {
+    throw new Error(`GitHub Pages configuration request failed with HTTP ${current.status}`);
+  }
+  const created = await fetchImpl(`${repositoryUrl}/pages`, {
+    method: 'POST', headers: requestHeaders,
+    body: JSON.stringify({ source: { branch: 'gh-pages', path: '/' } })
+  });
+  const configuration = await json(created, 'Pages activation');
+  return Object.freeze({ created: true, url: configuration.html_url, runUrl: run.html_url });
+}

package/src/github-repository-secret.js

@@ -0,0 +1,82 @@
+import sodium from 'libsodium-wrappers';
+
+const GITHUB_API_VERSION = '2026-03-10';
+const OWNER_OR_REPOSITORY = /^[A-Za-z0-9_.-]+$/;
+const SECRET_NAME = /^[A-Z_][A-Z0-9_]*$/;
+
+function required(value, field, pattern) {
+  if (typeof value !== 'string' || !pattern.test(value)) {
+    throw new TypeError(`${field} is invalid`);
+  }
+  return value;
+}
+
+function requiredSecret(value, field) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${field} must not be empty`);
+  }
+  return value;
+}
+
+function headers(accessToken) {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${accessToken}`,
+    'content-type': 'application/json',
+    'x-github-api-version': GITHUB_API_VERSION
+  };
+}
+
+async function requireSuccess(response, operation) {
+  if (!response?.ok) {
+    const status = Number.isInteger(response?.status) ? response.status : 'unknown';
+    throw new Error(`GitHub ${operation} failed with HTTP ${status}`);
+  }
+}
+
+export async function installRepositorySecret({
+  owner,
+  repository,
+  accessToken,
+  secretName,
+  secretValue,
+  fetchImpl = fetch,
+  sodiumImpl = sodium
+}) {
+  const normalizedOwner = required(owner, 'owner', OWNER_OR_REPOSITORY);
+  const normalizedRepository = required(repository, 'repository', OWNER_OR_REPOSITORY);
+  const normalizedSecretName = required(secretName, 'secretName', SECRET_NAME);
+  const token = requiredSecret(accessToken, 'accessToken');
+  const plaintext = requiredSecret(secretValue, 'secretValue');
+
+  await sodiumImpl.ready;
+
+  const baseUrl = `https://api.github.com/repos/${encodeURIComponent(normalizedOwner)}/${encodeURIComponent(normalizedRepository)}/actions/secrets`;
+  const publicKeyResponse = await fetchImpl(`${baseUrl}/public-key`, {
+    method: 'GET',
+    headers: headers(token)
+  });
+  await requireSuccess(publicKeyResponse, 'repository public-key request');
+  const publicKeyPayload = await publicKeyResponse.json();
+  const keyId = requiredSecret(publicKeyPayload?.key_id, 'GitHub key_id');
+  const publicKey = requiredSecret(publicKeyPayload?.key, 'GitHub public key');
+
+  const ciphertext = sodiumImpl.crypto_box_seal(
+    sodiumImpl.from_string(plaintext),
+    sodiumImpl.from_base64(publicKey, sodiumImpl.base64_variants.ORIGINAL)
+  );
+  const encryptedValue = sodiumImpl.to_base64(
+    ciphertext,
+    sodiumImpl.base64_variants.ORIGINAL
+  );
+
+  const uploadResponse = await fetchImpl(
+    `${baseUrl}/${encodeURIComponent(normalizedSecretName)}`,
+    {
+      method: 'PUT',
+      headers: headers(token),
+      body: JSON.stringify({ encrypted_value: encryptedValue, key_id: keyId })
+    }
+  );
+  await requireSuccess(uploadResponse, 'repository secret upload');
+}

package/src/github-repository-variable.js

@@ -0,0 +1,55 @@
+const GITHUB_API_VERSION = '2026-03-10';
+const OWNER_OR_REPOSITORY = /^[A-Za-z0-9_.-]+$/;
+const VARIABLE_NAME = /^[A-Z_][A-Z0-9_]*$/;
+
+function required(value, field, pattern) {
+  if (typeof value !== 'string' || !pattern.test(value)) {
+    throw new TypeError(`${field} is invalid`);
+  }
+  return value;
+}
+
+function requiredValue(value, field) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${field} must not be empty`);
+  }
+  return value;
+}
+
+function headers(accessToken) {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${accessToken}`,
+    'content-type': 'application/json',
+    'x-github-api-version': GITHUB_API_VERSION
+  };
+}
+
+export async function installRepositoryVariable({
+  owner, repository, accessToken, variableName, variableValue, fetchImpl = fetch
+}) {
+  const normalizedOwner = required(owner, 'owner', OWNER_OR_REPOSITORY);
+  const normalizedRepository = required(repository, 'repository', OWNER_OR_REPOSITORY);
+  const normalizedName = required(variableName, 'variableName', VARIABLE_NAME);
+  const token = requiredValue(accessToken, 'accessToken');
+  const value = requiredValue(variableValue, 'variableValue');
+  const baseUrl = `https://api.github.com/repos/${encodeURIComponent(normalizedOwner)}/${encodeURIComponent(normalizedRepository)}/actions/variables`;
+  const requestHeaders = headers(token);
+  const update = await fetchImpl(`${baseUrl}/${encodeURIComponent(normalizedName)}`, {
+    method: 'PATCH',
+    headers: requestHeaders,
+    body: JSON.stringify({ name: normalizedName, value })
+  });
+  if (update.ok) return;
+  if (update.status !== 404) {
+    throw new Error(`GitHub repository variable update failed with HTTP ${update.status}`);
+  }
+  const create = await fetchImpl(baseUrl, {
+    method: 'POST',
+    headers: requestHeaders,
+    body: JSON.stringify({ name: normalizedName, value })
+  });
+  if (!create.ok) {
+    throw new Error(`GitHub repository variable creation failed with HTTP ${create.status}`);
+  }
+}

package/src/github-template-repository.js

@@ -0,0 +1,117 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+const GITHUB_API_VERSION = '2026-03-10';
+const REPOSITORY_IDENTITY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} is required`);
+  }
+  return value.trim();
+}
+
+function repositorySegment(value, field) {
+  const segment = requiredString(value, field);
+  if (!/^[A-Za-z0-9_.-]+$/.test(segment)) {
+    throw new TypeError(`${field} contains unsupported characters`);
+  }
+  return segment;
+}
+
+export async function generateRepositoryFromTemplate({
+  accessToken,
+  templateOwner,
+  templateRepository,
+  owner,
+  repository,
+  description,
+  fetchImpl = fetch
+}) {
+  const token = requiredString(accessToken, 'accessToken');
+  const sourceOwner = repositorySegment(templateOwner, 'templateOwner');
+  const sourceRepository = repositorySegment(templateRepository, 'templateRepository');
+  const targetOwner = repositorySegment(owner, 'owner');
+  const targetRepository = repositorySegment(repository, 'repository');
+  if (description != null && typeof description !== 'string') {
+    throw new TypeError('description must be a string');
+  }
+
+  const response = await fetchImpl(
+    `https://api.github.com/repos/${encodeURIComponent(sourceOwner)}/${encodeURIComponent(sourceRepository)}/generate`,
+    {
+      method: 'POST',
+      headers: {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+        'x-github-api-version': GITHUB_API_VERSION
+      },
+      body: JSON.stringify({
+        owner: targetOwner,
+        name: targetRepository,
+        description: description ?? '',
+        include_all_branches: false,
+        private: false
+      })
+    }
+  );
+  if (response.status !== 201) {
+    throw new Error(`GitHub template generation failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (payload == null || Array.isArray(payload) || typeof payload !== 'object') {
+    throw new TypeError('GitHub repository response must be a JSON object');
+  }
+  const fullName = requiredString(payload.full_name, 'full_name');
+  if (!REPOSITORY_IDENTITY.test(fullName)) {
+    throw new TypeError('GitHub repository response contains an invalid full_name');
+  }
+  if (fullName.toLowerCase() !== `${targetOwner}/${targetRepository}`.toLowerCase()) {
+    throw new TypeError('GitHub generated an unexpected repository');
+  }
+
+  const cloneUrl = new URL(requiredString(payload.clone_url, 'clone_url'));
+  if (
+    cloneUrl.protocol !== 'https:'
+    || cloneUrl.hostname !== 'github.com'
+    || cloneUrl.username !== ''
+    || cloneUrl.password !== ''
+    || cloneUrl.search !== ''
+    || cloneUrl.hash !== ''
+    || cloneUrl.pathname.toLowerCase() !== `/${fullName}.git`.toLowerCase()
+  ) {
+    throw new TypeError('GitHub repository response contains an invalid clone_url');
+  }
+
+  return Object.freeze({ fullName, cloneUrl: cloneUrl.href });
+}
+
+export function cloneRepository({ cloneUrl, target, spawnProcess = spawn }) {
+  const source = new URL(requiredString(cloneUrl, 'cloneUrl'));
+  if (
+    source.protocol !== 'https:'
+    || source.hostname !== 'github.com'
+    || source.username !== ''
+    || source.password !== ''
+    || source.search !== ''
+    || source.hash !== ''
+  ) {
+    throw new TypeError('cloneUrl must be an uncredentialed GitHub HTTPS URL');
+  }
+  const resolvedTarget = path.resolve(requiredString(target, 'target'));
+
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['clone', source.href, resolvedTarget], {
+      cwd: path.dirname(resolvedTarget),
+      shell: false,
+      stdio: 'inherit'
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git clone terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git clone exited with code ${code}`));
+      else resolve(resolvedTarget);
+    });
+  });
+}

package/src/hook-command.js

@@ -0,0 +1,64 @@
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const MARKER = '// Managed by @rathnasgala/cli. Do not edit.\n';
+const HOOK = `#!/usr/bin/env node
+${MARKER}const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const root = process.cwd();
+const executable = path.join(
+  root,
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'gala.cmd' : 'gala'
+);
+const result = spawnSync(executable, ['validate', '--root', root], {
+  cwd: root,
+  shell: false,
+  stdio: 'inherit'
+});
+if (result.error) {
+  console.error('Gala validation hook failed to start:', result.error.message);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);
+`;
+
+async function metadata(file, allowMissing = false) {
+  try {
+    return await lstat(file);
+  } catch (error) {
+    if (allowMissing && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function installPrePushHook(root) {
+  const resolvedRoot = path.resolve(root);
+  const gitDirectory = path.join(resolvedRoot, '.git');
+  const gitMetadata = await metadata(gitDirectory);
+  if (!gitMetadata.isDirectory() || gitMetadata.isSymbolicLink()) {
+    throw new TypeError('.git must be a real directory');
+  }
+
+  const hooksDirectory = path.join(gitDirectory, 'hooks');
+  const hooksMetadata = await metadata(hooksDirectory, true);
+  if (hooksMetadata?.isSymbolicLink() || (hooksMetadata && !hooksMetadata.isDirectory())) {
+    throw new TypeError('.git/hooks must be a real directory');
+  }
+  if (!hooksMetadata) await mkdir(hooksDirectory);
+
+  const target = path.join(hooksDirectory, 'pre-push');
+  const existing = await metadata(target, true);
+  if (existing) {
+    if (!existing.isFile() || existing.isSymbolicLink()) {
+      throw new TypeError('Existing pre-push hook must be a regular file');
+    }
+    if (await readFile(target, 'utf8') === HOOK) return { target, installed: false };
+    throw new Error('Refusing to overwrite an existing pre-push hook');
+  }
+
+  await writeFile(target, HOOK, { encoding: 'utf8', flag: 'wx', mode: 0o755 });
+  return { target, installed: true };
+}