@rathnasgala/cli 0.0.22 → 1.1.4

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';

package/src/doctor-command.js

@@ -1,214 +0,0 @@
-import { createHash } from 'node:crypto';
-import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { readPublicationState, PUBLICATION_STATE_PATH } from './publication-state.js';
-
-async function sha256(file) {
-  return createHash('sha256').update(await readFile(file)).digest('hex');
-}
-
-export async function diagnoseFramework(root) {
-  const manifestPath = managedPath(root, '.gala/managed-files.json');
-  let manifest;
-  try {
-    await assertSafeAncestors(root, manifestPath);
-    await assertNotSymbolicLink(manifestPath, false);
-    manifest = parseManifest(await readFile(manifestPath, 'utf8'));
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return [{ path: '.gala/managed-files.json', status: 'missing-manifest' }];
-    }
-    throw new TypeError(`Invalid managed-file manifest: ${error.message}`);
-  }
-
-  return diagnoseAgainstManifest(root, manifest);
-}
-
-export async function diagnosePublicationState(root) {
-  try {
-    await readPublicationState(root);
-    return { path: PUBLICATION_STATE_PATH.split(path.sep).join('/'), status: 'valid' };
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return { path: PUBLICATION_STATE_PATH.split(path.sep).join('/'), status: 'missing' };
-    }
-    return {
-      path: PUBLICATION_STATE_PATH.split(path.sep).join('/'),
-      status: 'invalid',
-      detail: error.message
-    };
-  }
-}
-
-async function diagnoseAgainstManifest(root, manifest) {
-  const findings = [];
-  for (const [relativePath, expectedHash] of Object.entries(manifest.files)) {
-    if (relativePath === '.gala/managed-files.json') {
-      throw new TypeError('Managed-file manifest cannot manage itself');
-    }
-    const file = managedPath(root, relativePath);
-    try {
-      await assertSafeAncestors(root, file);
-      await assertNotSymbolicLink(file, false);
-      const actualHash = await sha256(file);
-      findings.push({
-        path: relativePath,
-        status: actualHash === expectedHash ? 'intact' : 'modified'
-      });
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      findings.push({ path: relativePath, status: 'missing' });
-    }
-  }
-  return findings;
-}
-
-function parseManifest(source) {
-  const manifest = JSON.parse(source);
-  if (manifest.schemaVersion !== 1 || manifest.files == null || Array.isArray(manifest.files)) {
-    throw new TypeError('Unsupported managed-file manifest schema');
-  }
-  return manifest;
-}
-
-function managedPath(root, relativePath) {
-  if (path.isAbsolute(relativePath)) throw new TypeError(`Managed path must be relative: ${relativePath}`);
-  const resolvedRoot = path.resolve(root);
-  const resolved = path.resolve(resolvedRoot, ...relativePath.split('/'));
-  const relation = path.relative(resolvedRoot, resolved);
-  if (relation.startsWith('..') || path.isAbsolute(relation)) {
-    throw new TypeError(`Managed path escapes the site root: ${relativePath}`);
-  }
-  const [firstSegment] = relation.split(path.sep);
-  const protectedFile = new Set([
-    '.engagement-snapshot.json',
-    '.gala/publication-state.yml',
-    '.github/workflows/publish.yml',
-    'CNAME',
-    'custom.css',
-    'site.config.yml'
-  ]).has(relation);
-  if (
-    protectedFile
-    || firstSegment === '.git'
-    || firstSegment === 'content'
-    || relation === '.env'
-    || (relation.startsWith('.env.') && relation !== '.env.example')
-  ) {
-    throw new TypeError(`Author-owned path cannot be managed: ${relativePath}`);
-  }
-  return resolved;
-}
-
-async function assertNotSymbolicLink(file, allowMissing) {
-  try {
-    const metadata = await lstat(file);
-    if (metadata.isSymbolicLink()) throw new TypeError(`Refusing symbolic link: ${file}`);
-    return metadata;
-  } catch (error) {
-    if (allowMissing && error.code === 'ENOENT') return null;
-    throw error;
-  }
-}
-
-async function assertSafeAncestors(root, file) {
-  const resolvedRoot = path.resolve(root);
-  const segments = path.relative(resolvedRoot, path.dirname(file)).split(path.sep).filter(Boolean);
-  let cursor = resolvedRoot;
-  for (const segment of segments) {
-    cursor = path.join(cursor, segment);
-    const metadata = await assertNotSymbolicLink(cursor, true);
-    if (metadata == null) return;
-    if (!metadata.isDirectory()) throw new TypeError(`Managed path ancestor is not a directory: ${cursor}`);
-  }
-}
-
-export async function repairFramework(root, sourceRoot, { renameImpl = rename, siteConfiguration } = {}) {
-  const manifestPath = path.resolve(root, '.gala', 'managed-files.json');
-  const sourceManifestPath = path.resolve(sourceRoot, '.gala', 'managed-files.json');
-  await assertSafeAncestors(sourceRoot, sourceManifestPath);
-  const sourceManifestMetadata = await assertNotSymbolicLink(sourceManifestPath, false);
-  if (!sourceManifestMetadata.isFile()) throw new TypeError('Trusted manifest must be a regular file');
-  const sourceManifest = await readFile(sourceManifestPath);
-  const manifest = parseManifest(sourceManifest.toString('utf8'));
-  await assertSafeAncestors(root, manifestPath);
-  await assertNotSymbolicLink(manifestPath, true);
-
-  const findings = await diagnoseAgainstManifest(root, manifest);
-  const repairTargets = findings.filter(({ status }) => status === 'missing' || status === 'modified');
-  const validated = [];
-
-  // Validate the entire repair set before replacing the first target.
-  for (const finding of repairTargets) {
-    const expectedHash = manifest.files[finding.path];
-    const source = managedPath(sourceRoot, finding.path);
-    const target = managedPath(root, finding.path);
-    await assertSafeAncestors(sourceRoot, source);
-    await assertSafeAncestors(root, target);
-    const sourceMetadata = await assertNotSymbolicLink(source, false);
-    if (!sourceMetadata.isFile()) throw new TypeError(`Repair source is not a file: ${finding.path}`);
-    const targetMetadata = await assertNotSymbolicLink(target, true);
-    if (await sha256(source) !== expectedHash) {
-      throw new TypeError(`Repair source hash mismatch: ${finding.path}`);
-    }
-    validated.push({ ...finding, source, target, targetExists: targetMetadata != null });
-  }
-
-  let existingManifest = null;
-  try { existingManifest = await readFile(manifestPath); } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  if (!existingManifest?.equals(sourceManifest)) {
-    validated.push({
-      path: '.gala/managed-files.json',
-      target: manifestPath,
-      bytes: sourceManifest,
-      targetExists: existingManifest != null
-    });
-  }
-  if (siteConfiguration != null) {
-    const configTarget = path.resolve(root, 'site.config.yml');
-    await assertSafeAncestors(root, configTarget);
-    const configMetadata = await assertNotSymbolicLink(configTarget, false);
-    if (!configMetadata.isFile()) throw new TypeError('site.config.yml must be a regular file');
-    validated.push({
-      path: 'site.config.yml', target: configTarget,
-      bytes: Buffer.from(siteConfiguration), targetExists: true
-    });
-  }
-
-  const transaction = `${process.pid}-${Date.now()}`;
-  const prepared = [];
-  try {
-    for (const item of validated) {
-      await mkdir(path.dirname(item.target), { recursive: true });
-      const temporary = `${item.target}.gala-repair-${transaction}`;
-      const backup = `${item.target}.gala-backup-${transaction}`;
-      await writeFile(temporary, item.bytes ?? await readFile(item.source), { flag: 'wx' });
-      prepared.push({ ...item, temporary, backup, backedUp: false, installed: false });
-    }
-    for (const item of prepared) {
-      if (item.targetExists) {
-        await renameImpl(item.target, item.backup);
-        item.backedUp = true;
-      }
-      await renameImpl(item.temporary, item.target);
-      item.installed = true;
-    }
-  } catch (error) {
-    const rollbackErrors = [];
-    for (const item of [...prepared].reverse()) {
-      try {
-        if (item.installed) await rm(item.target, { force: true });
-        if (item.backedUp) await renameImpl(item.backup, item.target);
-        await rm(item.temporary, { force: true });
-      } catch (rollbackError) { rollbackErrors.push(rollbackError); }
-    }
-    if (rollbackErrors.length > 0) {
-      throw new AggregateError([error, ...rollbackErrors], 'Framework repair and rollback failed');
-    }
-    throw error;
-  }
-  for (const item of prepared) if (item.backedUp) await rm(item.backup);
-  return prepared.map(({ path: repairedPath }) => repairedPath);
-}

package/src/entitlement-client.js

@@ -1,26 +0,0 @@
-const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
-const FIELDS = ['expiresAt', 'issuedAt', 'keyId', 'signature', 'siteId', 'tier'];
-
-export async function fetchAttributionEntitlement({ siteId, credential, fetchImpl = fetch }) {
-  if (!ULID.test(siteId)) throw new TypeError('siteId must be a canonical ULID');
-  const endpoint = new URL(`/v1/sites/${siteId}/attribution-entitlement`, credential.apiBaseUrl);
-  const loopback = endpoint.protocol === 'http:'
-    && ['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname);
-  if ((endpoint.protocol !== 'https:' && !loopback) || endpoint.username || endpoint.password) {
-    throw new TypeError('Gala API URL must be credential-free HTTPS or HTTP loopback');
-  }
-  const response = await fetchImpl(endpoint, {
-    headers: { Authorization: `Bearer ${credential.accessToken}`, Accept: 'application/json' }
-  });
-  if (!response.ok) throw new Error(`Attribution entitlement retrieval failed with HTTP ${response.status}`);
-  const artifact = await response.json();
-  if (artifact == null || Array.isArray(artifact) || typeof artifact !== 'object'
-      || Object.keys(artifact).sort().join('\0') !== FIELDS.join('\0')
-      || artifact.siteId !== siteId || artifact.tier !== 'PAID'
-      || !['issuedAt', 'expiresAt', 'keyId', 'signature'].every(
-        (field) => typeof artifact[field] === 'string' && artifact[field].length > 0
-      )) {
-    throw new TypeError('Attribution entitlement response is invalid');
-  }
-  return artifact;
-}

package/src/entitlement-command.js

@@ -1,74 +0,0 @@
-import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { parse } from 'yaml';
-import { readGalaCredential } from './gala-credential-store.js';
-import { fetchAttributionEntitlement } from './entitlement-client.js';
-
-const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
-const ARTIFACT = '.gala/entitlement.json';
-
-async function runGit(root, args) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('git', ['-C', root, ...args], { shell: false, stdio: 'inherit' });
-    child.once('error', reject);
-    child.once('exit', (code, signal) => {
-      if (signal) reject(new Error(`git terminated by signal ${signal}`));
-      else if (code !== 0) reject(new Error(`git ${args[0]} exited with code ${code}`));
-      else resolve();
-    });
-  });
-}
-
-async function commitArtifact(root) {
-  await runGit(root, ['add', '--', ARTIFACT]);
-  await runGit(root, ['commit', '--message', 'chore(gala): update attribution entitlement', '--', ARTIFACT]);
-  await runGit(root, ['push']);
-}
-
-export async function acquireAttributionEntitlement({
-  root = process.cwd(), readCredential = readGalaCredential,
-  fetchEntitlement = fetchAttributionEntitlement, commit = commitArtifact
-} = {}) {
-  const siteRoot = path.resolve(root);
-  const configTarget = path.join(siteRoot, 'site.config.yml');
-  const metadata = await lstat(configTarget);
-  if (!metadata.isFile() || metadata.isSymbolicLink()) {
-    throw new TypeError('site.config.yml must be a regular file');
-  }
-  const config = parse(await readFile(configTarget, 'utf8'));
-  const siteId = config?.site?.id;
-  if (!ULID.test(siteId)) throw new TypeError('site.config.yml site.id must be a canonical ULID');
-  const artifact = await fetchEntitlement({ siteId, credential: await readCredential() });
-  const directory = path.join(siteRoot, '.gala');
-  await mkdir(directory, { recursive: true });
-  const directoryMetadata = await lstat(directory);
-  if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
-    throw new TypeError('.gala must be a real directory');
-  }
-  const target = path.join(siteRoot, ARTIFACT);
-  try {
-    const current = await lstat(target);
-    if (!current.isFile() || current.isSymbolicLink()) {
-      throw new TypeError('Attribution entitlement must be a regular file');
-    }
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
-  try {
-    if (await readFile(target, 'utf8') === serialized) return Object.freeze({ changed: false, siteId });
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  const temporary = `${target}.gala-${process.pid}`;
-  try {
-    await writeFile(temporary, serialized, { flag: 'wx' });
-    await rename(temporary, target);
-  } catch (error) {
-    await rm(temporary, { force: true });
-    throw error;
-  }
-  await commit(siteRoot);
-  return Object.freeze({ changed: true, siteId });
-}

package/src/evaluation-date.js

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

package/src/gala-credential-health.js

@@ -1,34 +0,0 @@
-/**
- * Whether a stored Gala credential is one the server will still accept.
- *
- * `readGalaCredential` can only check what is written in the file — schema and expiry — and a
- * credential can satisfy both while the API refuses it outright. It happened: the API stopped
- * putting a `tenant` claim in its tokens and now rejects any token that still carries one
- * (Rs256JwtCodec: "Legacy tenant-bearing token requires reauthentication"). Tokens minted before
- * that change have a month-long expiry, so every command using one sent a bearer the server had
- * already decided to refuse, and reported it as whatever call happened to fail first.
- *
- * Expiry is not the only way a credential dies. It can be revoked, the signing key can rotate, the
- * claim set can change again. So this does not special-case the `tenant` claim: it asks the server,
- * once, and treats 401 as "this credential is finished" — which is true whatever the reason.
- */
-const PROBE_PATH = '/v1/me/sites';
-
-/**
- * Answers whether the API still accepts this credential.
- *
- * A network failure is deliberately not an answer: refusing to run because the machine is briefly
- * offline, or forcing a sign-in the writer does not need, are both worse than letting the real
- * call fail with its own error.
- */
-export async function galaCredentialAccepted({ apiBaseUrl, accessToken, fetchImpl = fetch }) {
-  let response;
-  try {
-    response = await fetchImpl(`${String(apiBaseUrl).replace(/\/$/, '')}${PROBE_PATH}`, {
-      headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` }
-    });
-  } catch {
-    return true;
-  }
-  return response.status !== 401;
-}

package/src/gala-credential-store.js

@@ -1,115 +0,0 @@
-import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-
-export function galaCredentialPath({
-  platform = process.platform,
-  environment = process.env,
-  home = os.homedir()
-} = {}) {
-  if (platform === 'win32') {
-    const root = environment.APPDATA;
-    if (!root) throw new Error('APPDATA is required to store Gala credentials on Windows');
-    return path.join(root, 'Gala', 'credentials.json');
-  }
-  if (platform === 'darwin') {
-    return path.join(home, 'Library', 'Application Support', 'Gala', 'credentials.json');
-  }
-  const root = environment.XDG_CONFIG_HOME || path.join(home, '.config');
-  return path.join(root, 'gala', 'credentials.json');
-}
-
-async function regularOrMissing(target, label) {
-  try {
-    const metadata = await lstat(target);
-    if (metadata.isSymbolicLink() || !metadata.isFile()) {
-      throw new TypeError(`${label} must be a regular file`);
-    }
-    return true;
-  } catch (error) {
-    if (error.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-export async function writeGalaCredential({
-  accessToken,
-  expiresAt,
-  apiBaseUrl,
-  target = galaCredentialPath()
-}) {
-  if (typeof accessToken !== 'string' || accessToken === '') throw new TypeError('accessToken is required');
-  if (!(expiresAt instanceof Date) || Number.isNaN(expiresAt.getTime())) {
-    throw new TypeError('expiresAt must be a valid Date');
-  }
-  const base = new URL(apiBaseUrl);
-  const loopback = base.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(base.hostname);
-  if ((base.protocol !== 'https:' && !loopback) || base.username || base.password
-      || base.search || base.hash) {
-    throw new TypeError('apiBaseUrl must be credential-free HTTPS (or HTTP loopback) without query or fragment');
-  }
-  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('Gala credential directory must be a real directory');
-  }
-  await chmod(directory, 0o700);
-  const exists = await regularOrMissing(target, 'Gala credential file');
-  const temporary = `${target}.gala-${process.pid}`;
-  const backup = `${target}.gala-backup-${process.pid}`;
-  const content = `${JSON.stringify({
-    schemaVersion: 1,
-    apiBaseUrl: base.href,
-    accessToken,
-    expiresAt: expiresAt.toISOString()
-  })}\n`;
-  try {
-    await writeFile(temporary, content, { 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 readGalaCredential({ target = galaCredentialPath(), now = new Date() } = {}) {
-  if (!await regularOrMissing(target, 'Gala credential file')) {
-    throw new Error('Gala authentication is missing; run `gala auth`');
-  }
-  const payload = JSON.parse(await readFile(target, 'utf8'));
-  if (payload?.schemaVersion !== 1 || typeof payload.accessToken !== 'string'
-      || typeof payload.apiBaseUrl !== 'string' || typeof payload.expiresAt !== 'string') {
-    throw new TypeError('Gala credential file has an unsupported schema');
-  }
-  const expiresAt = new Date(payload.expiresAt);
-  if (Number.isNaN(expiresAt.getTime()) || expiresAt <= now) {
-    throw new Error('Gala authentication expired; run `gala auth` again');
-  }
-  return Object.freeze({
-    accessToken: payload.accessToken,
-    apiBaseUrl: payload.apiBaseUrl,
-    expiresAt
-  });
-}
-
-/**
- * Removes a credential the server no longer accepts.
- *
- * Leaving a refused token on disk means every later command rediscovers that it is refused, and
- * `readGalaCredential` cannot tell the difference — the file is well-formed and unexpired. Deleting
- * it is what makes the next run ask for a sign-in instead of failing again.
- */
-export async function forgetGalaCredential({ target = galaCredentialPath() } = {}) {
-  await rm(target, { force: true });
-}