hugo-extended 0.154.3 → 0.154.4

package/dist/lib/env.d.mts

@@ -0,0 +1,62 @@
+//#region src/lib/env.d.ts
+/**
+ * Centralized environment variable handling for hugo-extended.
+ *
+ * All environment variables are prefixed with `HUGO_` and provide ways to
+ * customize the installation and runtime behavior of the package.
+ *
+ * @module
+ */
+/**
+ * Typed environment configuration object.
+ * Provides a clean API for accessing all Hugo environment variables.
+ */
+interface HugoEnvConfig {
+  /** Override the Hugo version to install (ignores package.json) */
+  overrideVersion: string | undefined;
+  /** Force vanilla Hugo instead of Extended edition */
+  forceStandard: boolean;
+  /** Skip the postinstall binary download */
+  skipInstall: boolean;
+  /** Path to a pre-existing Hugo binary */
+  binPath: string | undefined;
+  /** Custom base URL for Hugo release downloads */
+  downloadBaseUrl: string | undefined;
+  /** Skip SHA-256 checksum verification */
+  skipChecksum: boolean;
+  /** Suppress installation progress output */
+  quiet: boolean;
+}
+/**
+ * Reads and parses all Hugo environment variables.
+ *
+ * This function reads from `process.env` each time it's called,
+ * so it will pick up any runtime changes to environment variables.
+ *
+ * @returns Parsed environment configuration
+ *
+ * @example
+ * ```typescript
+ * import { getEnvConfig } from './lib/env';
+ *
+ * const config = getEnvConfig();
+ * if (config.skipInstall) {
+ *   console.log('Skipping installation');
+ * }
+ * ```
+ */
+declare function getEnvConfig(): HugoEnvConfig;
+/**
+ * Metadata about all supported environment variables.
+ * Useful for documentation generation or help output.
+ */
+declare const ENV_VAR_DOCS: {
+  key: string;
+  name: string;
+  aliases: string[] | never[];
+  description: string;
+  type: string;
+  default: false | undefined;
+}[];
+//#endregion
+export { ENV_VAR_DOCS, HugoEnvConfig, getEnvConfig };

package/dist/lib/env.mjs

@@ -0,0 +1,138 @@
+//#region src/lib/env.ts
+/**
+* Parses a boolean environment variable.
+* Truthy values: "1", "true", "yes", "on" (case-insensitive)
+* Falsy values: "0", "false", "no", "off", undefined, empty string
+*/
+function parseBoolean(value) {
+	if (!value) return false;
+	const normalized = value.toLowerCase().trim();
+	return [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes(normalized);
+}
+/**
+* Parses a string environment variable (returns undefined if empty).
+*/
+function parseString(value) {
+	if (!value || value.trim() === "") return void 0;
+	return value.trim();
+}
+/**
+* Parses a version string, stripping any leading "v" prefix.
+*/
+function parseVersion(value) {
+	const str = parseString(value);
+	if (!str) return void 0;
+	return str.startsWith("v") ? str.slice(1) : str;
+}
+/**
+* Gets the first defined value from a list of environment variable names.
+*/
+function getFirstDefined(names) {
+	for (const name of names) {
+		const value = process.env[name];
+		if (value !== void 0 && value !== "") return value;
+	}
+}
+/**
+* All supported environment variable configurations.
+*/
+const ENV_VARS = {
+	overrideVersion: {
+		name: "HUGO_OVERRIDE_VERSION",
+		aliases: [],
+		description: "Override the Hugo version to install",
+		parse: parseVersion,
+		defaultValue: void 0
+	},
+	forceStandard: {
+		name: "HUGO_NO_EXTENDED",
+		aliases: ["HUGO_FORCE_STANDARD"],
+		description: "Force vanilla Hugo instead of Extended edition",
+		parse: parseBoolean,
+		defaultValue: false
+	},
+	skipInstall: {
+		name: "HUGO_SKIP_DOWNLOAD",
+		aliases: [],
+		description: "Skip the postinstall binary download",
+		parse: parseBoolean,
+		defaultValue: false
+	},
+	binPath: {
+		name: "HUGO_BIN_PATH",
+		aliases: [],
+		description: "Path to a pre-existing Hugo binary",
+		parse: parseString,
+		defaultValue: void 0
+	},
+	downloadBaseUrl: {
+		name: "HUGO_MIRROR_BASE_URL",
+		aliases: [],
+		description: "Custom base URL for Hugo release downloads",
+		parse: parseString,
+		defaultValue: void 0
+	},
+	skipChecksum: {
+		name: "HUGO_SKIP_CHECKSUM",
+		aliases: ["HUGO_SKIP_VERIFY"],
+		description: "Skip SHA-256 checksum verification",
+		parse: parseBoolean,
+		defaultValue: false
+	},
+	quiet: {
+		name: "HUGO_QUIET",
+		aliases: ["HUGO_SILENT"],
+		description: "Suppress installation progress output",
+		parse: parseBoolean,
+		defaultValue: false
+	}
+};
+/**
+* Reads and parses all Hugo environment variables.
+*
+* This function reads from `process.env` each time it's called,
+* so it will pick up any runtime changes to environment variables.
+*
+* @returns Parsed environment configuration
+*
+* @example
+* ```typescript
+* import { getEnvConfig } from './lib/env';
+*
+* const config = getEnvConfig();
+* if (config.skipInstall) {
+*   console.log('Skipping installation');
+* }
+* ```
+*/
+function getEnvConfig() {
+	return {
+		overrideVersion: ENV_VARS.overrideVersion.parse(getFirstDefined([ENV_VARS.overrideVersion.name, ...ENV_VARS.overrideVersion.aliases ?? []])),
+		forceStandard: ENV_VARS.forceStandard.parse(getFirstDefined([ENV_VARS.forceStandard.name, ...ENV_VARS.forceStandard.aliases ?? []])),
+		skipInstall: ENV_VARS.skipInstall.parse(getFirstDefined([ENV_VARS.skipInstall.name, ...ENV_VARS.skipInstall.aliases ?? []])),
+		binPath: ENV_VARS.binPath.parse(getFirstDefined([ENV_VARS.binPath.name, ...ENV_VARS.binPath.aliases ?? []])),
+		downloadBaseUrl: ENV_VARS.downloadBaseUrl.parse(getFirstDefined([ENV_VARS.downloadBaseUrl.name, ...ENV_VARS.downloadBaseUrl.aliases ?? []])),
+		skipChecksum: ENV_VARS.skipChecksum.parse(getFirstDefined([ENV_VARS.skipChecksum.name, ...ENV_VARS.skipChecksum.aliases ?? []])),
+		quiet: ENV_VARS.quiet.parse(getFirstDefined([ENV_VARS.quiet.name, ...ENV_VARS.quiet.aliases ?? []]))
+	};
+}
+/**
+* Metadata about all supported environment variables.
+* Useful for documentation generation or help output.
+*/
+const ENV_VAR_DOCS = Object.entries(ENV_VARS).map(([key, config]) => ({
+	key,
+	name: config.name,
+	aliases: config.aliases ?? [],
+	description: config.description,
+	type: config.defaultValue === void 0 ? "string" : typeof config.defaultValue === "boolean" ? "boolean" : "string",
+	default: config.defaultValue
+}));
+
+//#endregion
+export { ENV_VAR_DOCS, getEnvConfig };

package/dist/lib/install.d.mts

@@ -0,0 +1,66 @@
+//#region src/lib/install.d.ts
+/**
+ * Archive types supported by the installer.
+ */
+type ArchiveType = "zip" | "tar.gz" | "pkg" | null;
+/**
+ * Detects the archive type from a filename based on its extension.
+ *
+ * @param filename - The filename to check
+ * @returns The detected archive type, or null if unknown
+ */
+declare function getArchiveType(filename: string): ArchiveType;
+/**
+ * Parses a checksums file content into a lookup map.
+ *
+ * The checksums file format is: "sha256hash  filename" (hash followed by whitespace and filename).
+ * This is the standard format used by Hugo releases.
+ *
+ * @param content - The raw content of the checksums file
+ * @returns A Map of filename to SHA-256 hash
+ */
+declare function parseChecksumFile(content: string): Map<string, string>;
+/**
+ * Extracts a Hugo binary from a macOS .pkg file without requiring sudo.
+ *
+ * Uses `pkgutil --expand-full` to expand the package, then locates and copies
+ * the Hugo binary from the payload to the destination directory.
+ *
+ * The Hugo .pkg structure after expansion contains:
+ * - A "Payload" directory containing the hugo binary directly
+ * - Or a component package directory with Payload inside
+ *
+ * @param pkgPath - The path to the .pkg file to extract
+ * @param destDir - The directory where the hugo binary should be placed
+ * @throws {Error} If extraction fails, Payload is not found, or hugo binary is missing
+ * @see https://github.com/jmooring/hvm/commit/16eb55ae4965b5d2e414061085490a90fe7ea73e
+ */
+declare function extractPkg(pkgPath: string, destDir: string): void;
+/**
+ * Downloads, verifies, and installs Hugo (Extended when available) for the current platform.
+ *
+ * This function handles the complete installation process:
+ * - Determines the correct Hugo release file for the current platform and architecture
+ * - Downloads the release file and checksums from GitHub (or custom mirror)
+ * - Verifies the integrity of the downloaded file using SHA-256 checksums (unless HUGO_SKIP_CHECKSUM is set)
+ * - Extracts the binary (platform-specific):
+ *   - macOS v0.153.0+: Extracts from .pkg using pkgutil (no sudo required)
+ *   - macOS pre-v0.153.0: Extracts from .tar.gz archive
+ *   - Windows: Extracts from .zip archive
+ *   - Linux/BSD: Extracts from .tar.gz archive
+ * - Sets appropriate file permissions on Unix-like systems
+ * - Displays the installed Hugo version
+ *
+ * Environment variables that affect installation:
+ * - HUGO_OVERRIDE_VERSION: Install a different Hugo version
+ * - HUGO_NO_EXTENDED: Force vanilla Hugo instead of Extended
+ * - HUGO_MIRROR_BASE_URL: Custom download mirror
+ * - HUGO_SKIP_CHECKSUM: Skip SHA-256 verification
+ * - HUGO_QUIET: Suppress progress output
+ *
+ * @throws {Error} If the platform is unsupported, download fails, checksum doesn't match, or installation fails
+ * @returns A promise that resolves with the absolute path to the installed Hugo binary
+ */
+declare function install(): Promise<string>;
+//#endregion
+export { ArchiveType, install as default, extractPkg, getArchiveType, parseChecksumFile };

package/dist/lib/install.mjs

@@ -0,0 +1,190 @@
+import { getEnvConfig } from "./env.mjs";
+import { getBinFilename, getBinVersion, getChecksumFilename, getPkgVersion, getReleaseFilename, getReleaseUrl, isExtended, logger } from "./utils.mjs";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import crypto from "node:crypto";
+import os from "node:os";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import AdmZip from "adm-zip";
+import * as tar from "tar";
+
+//#region src/lib/install.ts
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+* Detects the archive type from a filename based on its extension.
+*
+* @param filename - The filename to check
+* @returns The detected archive type, or null if unknown
+*/
+function getArchiveType(filename) {
+	if (filename.endsWith(".zip")) return "zip";
+	if (filename.endsWith(".tar.gz")) return "tar.gz";
+	if (filename.endsWith(".pkg")) return "pkg";
+	return null;
+}
+/**
+* Parses a checksums file content into a lookup map.
+*
+* The checksums file format is: "sha256hash  filename" (hash followed by whitespace and filename).
+* This is the standard format used by Hugo releases.
+*
+* @param content - The raw content of the checksums file
+* @returns A Map of filename to SHA-256 hash
+*/
+function parseChecksumFile(content) {
+	const checksums = /* @__PURE__ */ new Map();
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const tokens = trimmed.split(/\s+/);
+		if (tokens.length >= 2) {
+			const hash = tokens[0];
+			const filename = tokens[tokens.length - 1];
+			checksums.set(filename, hash);
+		}
+	}
+	return checksums;
+}
+/**
+* Downloads a file from a URL to a local destination path.
+*
+* @param url - The URL to download the file from
+* @param dest - The local file path where the downloaded file will be saved
+* @throws {Error} If the download fails or the response is invalid
+* @returns A promise that resolves when the download is complete
+*/
+async function downloadFile(url, dest) {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download ${url}: ${response.statusText}`);
+	if (!response.body) throw new Error(`No response body from ${url}`);
+	await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(dest));
+}
+/**
+* Extracts a Hugo binary from a macOS .pkg file without requiring sudo.
+*
+* Uses `pkgutil --expand-full` to expand the package, then locates and copies
+* the Hugo binary from the payload to the destination directory.
+*
+* The Hugo .pkg structure after expansion contains:
+* - A "Payload" directory containing the hugo binary directly
+* - Or a component package directory with Payload inside
+*
+* @param pkgPath - The path to the .pkg file to extract
+* @param destDir - The directory where the hugo binary should be placed
+* @throws {Error} If extraction fails, Payload is not found, or hugo binary is missing
+* @see https://github.com/jmooring/hvm/commit/16eb55ae4965b5d2e414061085490a90fe7ea73e
+*/
+function extractPkg(pkgPath, destDir) {
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hugo-pkg-"));
+	try {
+		const expansionDir = path.join(tempDir, "expanded");
+		execSync(`pkgutil --expand-full "${pkgPath}" "${expansionDir}"`, { stdio: "pipe" });
+		const hugoPayload = path.join(expansionDir, "Payload", "hugo");
+		if (!fs.existsSync(hugoPayload)) throw new Error("Could not find hugo binary in expanded .pkg. Expected path: */Payload/hugo");
+		const destPath = path.join(destDir, getBinFilename());
+		fs.copyFileSync(hugoPayload, destPath);
+		fs.chmodSync(destPath, 493);
+	} finally {
+		fs.rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Verifies that a downloaded file matches its expected SHA-256 checksum.
+*
+* Downloads the checksums file from GitHub, extracts the expected checksum for the
+* specified filename, computes the actual checksum of the local file, and compares them.
+*
+* @param filePath - The local path to the file to verify
+* @param checksumUrl - The URL to the checksums file (usually checksums.txt from the release)
+* @param filename - The name of the file to find in the checksums file
+* @throws {Error} If checksums don't match, the checksums file can't be downloaded, or the filename isn't found
+* @returns A promise that resolves when verification is successful
+*/
+async function verifyChecksum(filePath, checksumUrl, filename) {
+	const response = await fetch(checksumUrl);
+	if (!response.ok) throw new Error(`Failed to download checksums: ${response.statusText}`);
+	const expectedChecksum = parseChecksumFile(await response.text()).get(filename);
+	if (!expectedChecksum) throw new Error(`Checksum for ${filename} not found in checksums file.`);
+	const fileBuffer = fs.readFileSync(filePath);
+	const hash = crypto.createHash("sha256");
+	hash.update(fileBuffer);
+	const actualChecksum = hash.digest("hex");
+	if (actualChecksum !== expectedChecksum) throw new Error(`Checksum mismatch! Expected ${expectedChecksum}, got ${actualChecksum}`);
+}
+/**
+* Downloads, verifies, and installs Hugo (Extended when available) for the current platform.
+*
+* This function handles the complete installation process:
+* - Determines the correct Hugo release file for the current platform and architecture
+* - Downloads the release file and checksums from GitHub (or custom mirror)
+* - Verifies the integrity of the downloaded file using SHA-256 checksums (unless HUGO_SKIP_CHECKSUM is set)
+* - Extracts the binary (platform-specific):
+*   - macOS v0.153.0+: Extracts from .pkg using pkgutil (no sudo required)
+*   - macOS pre-v0.153.0: Extracts from .tar.gz archive
+*   - Windows: Extracts from .zip archive
+*   - Linux/BSD: Extracts from .tar.gz archive
+* - Sets appropriate file permissions on Unix-like systems
+* - Displays the installed Hugo version
+*
+* Environment variables that affect installation:
+* - HUGO_OVERRIDE_VERSION: Install a different Hugo version
+* - HUGO_NO_EXTENDED: Force vanilla Hugo instead of Extended
+* - HUGO_MIRROR_BASE_URL: Custom download mirror
+* - HUGO_SKIP_CHECKSUM: Skip SHA-256 verification
+* - HUGO_QUIET: Suppress progress output
+*
+* @throws {Error} If the platform is unsupported, download fails, checksum doesn't match, or installation fails
+* @returns A promise that resolves with the absolute path to the installed Hugo binary
+*/
+async function install() {
+	const envConfig = getEnvConfig();
+	try {
+		const version = getPkgVersion();
+		const releaseFile = getReleaseFilename(version);
+		const checksumFile = getChecksumFilename(version);
+		const binFile = getBinFilename();
+		if (!releaseFile) throw new Error(`Are you sure this platform is supported? See: https://github.com/gohugoio/hugo/releases/tag/v${version}`);
+		if (!isExtended(releaseFile)) if (envConfig.forceStandard) logger.info("Installing vanilla Hugo (HUGO_NO_EXTENDED is set).");
+		else logger.warn("Hugo Extended isn't supported on this platform, downloading vanilla Hugo instead.");
+		const binDir = path.join(__dirname, "..", "..", "bin");
+		if (!fs.existsSync(binDir)) fs.mkdirSync(binDir, { recursive: true });
+		const releaseUrl = getReleaseUrl(version, releaseFile);
+		const checksumUrl = getReleaseUrl(version, checksumFile);
+		const downloadPath = path.join(binDir, releaseFile);
+		logger.info(`☁️ Downloading ${releaseFile}...`);
+		await downloadFile(releaseUrl, downloadPath);
+		if (envConfig.skipChecksum) logger.warn("Skipping checksum verification (HUGO_SKIP_CHECKSUM is set).");
+		else {
+			logger.info("🕵️ Verifying checksum...");
+			await verifyChecksum(downloadPath, checksumUrl, releaseFile);
+		}
+		logger.info("📦 Extracting...");
+		const archiveType = getArchiveType(releaseFile);
+		if (archiveType === "pkg") extractPkg(downloadPath, binDir);
+		else if (archiveType === "zip") new AdmZip(downloadPath).extractAllTo(binDir, true);
+		else if (archiveType === "tar.gz") await tar.x({
+			file: downloadPath,
+			cwd: binDir
+		});
+		else throw new Error(`Unexpected archive type for ${releaseFile}. Expected .zip, .tar.gz, or .pkg.`);
+		fs.unlinkSync(downloadPath);
+		const binPath = path.join(binDir, binFile);
+		if (fs.existsSync(binPath)) fs.chmodSync(binPath, 493);
+		logger.info("🎉 Hugo installed successfully!");
+		logger.info(getBinVersion(binPath));
+		return binPath;
+	} catch (error) {
+		logger.error("Hugo installation failed. :(");
+		throw error;
+	}
+}
+var install_default = install;
+
+//#endregion
+export { install_default as default, extractPkg, getArchiveType, parseChecksumFile };

package/dist/lib/utils.d.mts

@@ -0,0 +1,123 @@
+//#region src/lib/utils.d.ts
+/**
+ * Compares two semver version strings.
+ *
+ * @param a - First version string (e.g., "0.153.0")
+ * @param b - Second version string (e.g., "0.152.1")
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Checks if a version uses .pkg installers for macOS.
+ * Hugo v0.153.0+ uses .pkg, earlier versions use .tar.gz.
+ *
+ * @param version - The Hugo version to check
+ * @returns true if the version uses .pkg installers on macOS
+ */
+declare function usesMacOSPkg(version: string): boolean;
+/**
+ * Gets the Hugo version to install.
+ *
+ * Resolution order:
+ * 1. HUGO_OVERRIDE_VERSION environment variable (if set)
+ * 2. `hugoVersion` field in package.json (for emergency overrides)
+ * 3. `version` field in package.json (should match Hugo release)
+ *
+ * @throws {Error} If package.json cannot be found and no override is set
+ * @returns The version string (e.g., "0.88.1")
+ */
+declare function getPkgVersion(): string;
+/**
+ * Generates the full URL to a Hugo release file.
+ *
+ * By default, downloads from GitHub releases. Can be overridden with
+ * HUGO_MIRROR_BASE_URL for mirrors or air-gapped environments.
+ *
+ * @param version - The Hugo version number (e.g., "0.88.1")
+ * @param filename - The release filename (e.g., "hugo_extended_0.88.1_darwin-universal.pkg")
+ * @returns The complete download URL for the release file
+ */
+declare function getReleaseUrl(version: string, filename: string): string;
+/**
+ * Gets the Hugo binary filename for the current platform.
+ *
+ * @returns "hugo.exe" on Windows, "hugo" on all other platforms
+ */
+declare function getBinFilename(): string;
+/**
+ * Gets the absolute path to the Hugo binary.
+ *
+ * Resolution order:
+ * 1. HUGO_BIN_PATH environment variable (if set)
+ * 2. Local bin directory (./bin/hugo or ./bin/hugo.exe)
+ *
+ * @returns The absolute path to hugo binary
+ */
+declare function getBinPath(): string;
+/**
+ * Executes the Hugo binary and returns its version string.
+ *
+ * @param bin - The absolute path to the Hugo binary
+ * @returns The version output string (e.g., "hugo v0.88.1-5BC54738+extended darwin/arm64 BuildDate=...")
+ * @throws {Error} If the binary cannot be executed
+ */
+declare function getBinVersion(bin: string): string;
+/**
+ * Checks if the Hugo binary exists at the specified path.
+ *
+ * @param bin - The absolute path to check for the Hugo binary
+ * @returns `true` if the file exists, `false` if it doesn't
+ * @throws {Error} If an unexpected error occurs (other than ENOENT)
+ */
+declare function doesBinExist(bin: string): boolean;
+/**
+ * Determines the correct Hugo release filename for the current platform and architecture.
+ *
+ * Hugo Extended is available for:
+ * - macOS: x64 and ARM64 (universal binaries as of v0.102.0)
+ * - Linux: x64 and ARM64
+ * - Windows: x64 only
+ *
+ * Other platform/architecture combinations fall back to vanilla Hugo where available.
+ * Set HUGO_NO_EXTENDED=1 to force vanilla Hugo even on platforms that support Extended.
+ *
+ * Note: macOS uses .pkg installers starting from v0.153.0. Earlier versions use .tar.gz.
+ *
+ * @param version - The Hugo version number (e.g., "0.88.1")
+ * @returns The release filename if supported (e.g., "hugo_extended_0.88.1_darwin-universal.pkg"),
+ *          or `null` if the platform/architecture combination is not supported
+ */
+declare function getReleaseFilename(version: string): string | null;
+/**
+ * Generates the checksums filename for a given Hugo version.
+ *
+ * @param version - The Hugo version number (e.g., "0.88.1")
+ * @returns The checksums filename (e.g., "hugo_0.88.1_checksums.txt")
+ */
+declare function getChecksumFilename(version: string): string;
+/**
+ * Determines if a release filename corresponds to Hugo Extended or vanilla Hugo.
+ *
+ * @param releaseFile - The release filename to check (e.g., "hugo_extended_0.88.1_darwin-universal.pkg")
+ * @returns `true` if the release is Hugo Extended, `false` if it's vanilla Hugo
+ */
+declare function isExtended(releaseFile: string): boolean;
+/**
+ * Logger utility that respects the HUGO_QUIET setting.
+ */
+declare const logger: {
+  /**
+   * Log an info message (respects HUGO_QUIET).
+   */
+  info: (message: string) => void;
+  /**
+   * Log a warning message (respects HUGO_QUIET).
+   */
+  warn: (message: string) => void;
+  /**
+   * Log an error message (always shown, even in quiet mode).
+   */
+  error: (message: string) => void;
+};
+//#endregion
+export { compareVersions, doesBinExist, getBinFilename, getBinPath, getBinVersion, getChecksumFilename, getPkgVersion, getReleaseFilename, getReleaseUrl, isExtended, logger, usesMacOSPkg };