@wpelevator/wp-release 0.0.0-stage → 0.1.1

package/dist/filename.d.ts

@@ -0,0 +1,17 @@
+export declare const FILENAME_FORMAT = "{slug}.{version}";
+export interface FilenameValues {
+    /** Plugin or theme slug. */
+    slug: string;
+    /** Version, if known. */
+    version?: string | null;
+}
+/**
+ * Format the release filename (without an extension) from placeholders. The
+ * default format falls back to just the slug when the version is unknown.
+ *
+ * @param  format Format with {slug} and {version} placeholders.
+ * @param  values Placeholder values.
+ * @return Filename without an extension.
+ * @throws {ValidationError} If the format needs a version that is unknown.
+ */
+export declare function formatFilename(format: string, values: FilenameValues): string;

package/dist/filename.js

@@ -0,0 +1,23 @@
+import { ValidationError } from "./errors.js";
+export const FILENAME_FORMAT = '{slug}.{version}';
+/**
+ * Format the release filename (without an extension) from placeholders. The
+ * default format falls back to just the slug when the version is unknown.
+ *
+ * @param  format Format with {slug} and {version} placeholders.
+ * @param  values Placeholder values.
+ * @return Filename without an extension.
+ * @throws {ValidationError} If the format needs a version that is unknown.
+ */
+export function formatFilename(format, values) {
+    const { slug, version = null } = values;
+    if (!version && FILENAME_FORMAT === format) {
+        return slug;
+    }
+    if (!version && format.includes('{version}')) {
+        throw new ValidationError(`The filename format "${format}" needs a version, pass --version.`);
+    }
+    return format
+        .replaceAll('{slug}', slug)
+        .replaceAll('{version}', version ?? '');
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { run, commands, getHelp, getCommandHelp } from './cli.ts';
+export { getDeployInputFromArgs } from './commands/deploy-svn.ts';
+export { ValidationError, CredentialsError } from './errors.ts';
+export { Logger } from './logger.ts';
+export { SVN_URL, isPrerelease, normalizeTag, isTagRef, isValidSlug, isValidVersion, getDeployOptionErrors, getDeployOptionWarnings, resolveDeployOptions, } from './deploy-options.ts';
+export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules, selectFiles, } from './file-selection.ts';
+export { FILENAME_FORMAT, formatFilename } from './filename.ts';
+export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from './checksums.ts';
+export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from './package-meta.ts';
+export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from './zip.ts';
+export { readZipEntries, getZipEntryErrors, extractZip } from './unzip.ts';
+export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from './version-check.ts';
+export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from './svn.ts';
+export { syncDirectory, copyFileIfChanged } from './sync.ts';
+export { ASSET_MIME_TYPES, SvnDeploy } from './svn-deploy.ts';
+export type { CliIo } from './cli.ts';
+export type { Command, CommandContext, CommandOutcome, ParsedValues, } from './commands/command.ts';
+export type { DeployArgsInput } from './commands/deploy-svn.ts';
+export type { LoggerOptions, OutputStream } from './logger.ts';
+export type { DeployInput, DeployOptions } from './deploy-options.ts';
+export type { FileRules, FileSelection, FileSelectionInput, } from './file-selection.ts';
+export type { FilenameValues } from './filename.ts';
+export type { ChecksumAlgorithm, ChecksumsComparison, ChecksumsManifest, CreateChecksumsInput, ExpectedHashes, FileHashes, PackageType, VerifyChecksumsInput, } from './checksums.ts';
+export type { FindMainPluginFileInput, HeaderValues, PackageMeta, ParseFileHeadersInput, ReadPackageMetaInput, ReadmeMeta, } from './package-meta.ts';
+export type { CreateZipInput } from './zip.ts';
+export type { ExtractZipInput, ZipEntryInfo, ZipEntryType } from './unzip.ts';
+export type { FindVersionMismatchesInput, GitTagInput, VersionCheckResult, VersionMismatch, } from './version-check.ts';
+export type { SvnCheckoutInput, SvnCommandInput, SvnCommandOutput, SvnCommitInput, SvnCopyInput, SvnDepth, SvnOptions, SvnPathsInput, SvnPropsetInput, SvnRunner, SvnStatusEntry, SvnStatusType, SvnUpdateInput, } from './svn.ts';
+export type { SyncDirectoryInput, SyncResult } from './sync.ts';
+export type { CheckoutPath, DeployResult } from './svn-deploy.ts';

package/dist/index.js

@@ -0,0 +1,15 @@
+export { run, commands, getHelp, getCommandHelp } from "./cli.js";
+export { getDeployInputFromArgs } from "./commands/deploy-svn.js";
+export { ValidationError, CredentialsError } from "./errors.js";
+export { Logger } from "./logger.js";
+export { SVN_URL, isPrerelease, normalizeTag, isTagRef, isValidSlug, isValidVersion, getDeployOptionErrors, getDeployOptionWarnings, resolveDeployOptions, } from "./deploy-options.js";
+export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules, selectFiles, } from "./file-selection.js";
+export { FILENAME_FORMAT, formatFilename } from "./filename.js";
+export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from "./checksums.js";
+export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from "./package-meta.js";
+export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from "./zip.js";
+export { readZipEntries, getZipEntryErrors, extractZip } from "./unzip.js";
+export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from "./version-check.js";
+export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from "./svn.js";
+export { syncDirectory, copyFileIfChanged } from "./sync.js";
+export { ASSET_MIME_TYPES, SvnDeploy } from "./svn-deploy.js";

package/dist/logger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stream that output is written to, like process.stdout.
+ */
+export interface OutputStream {
+    write: (text: string) => unknown;
+}
+export interface LoggerOptions {
+    /** Use GitHub Actions workflow commands. */
+    ci?: boolean;
+    /** Print errors only. */
+    quiet?: boolean;
+    /** Print debug messages. */
+    verbose?: boolean;
+    /** Stream for regular output. */
+    stdout?: OutputStream;
+    /** Stream for warnings and errors. */
+    stderr?: OutputStream;
+}
+/**
+ * Logger that prints plain text locally and GitHub Actions workflow commands in CI.
+ */
+export declare class Logger {
+    readonly ci: boolean;
+    readonly quiet: boolean;
+    readonly verbose: boolean;
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    constructor({ ci, quiet, verbose, stdout, stderr, }?: LoggerOptions);
+    info(message: string): void;
+    debug(message: string): void;
+    notice(message: string): void;
+    warning(message: string): void;
+    error(message: string): void;
+    /**
+     * Run a callback inside a collapsible log group.
+     *
+     * @param title    Group title.
+     * @param callback Callback to run inside the group.
+     * @return Callback result.
+     */
+    group<T>(title: string, callback: () => T | Promise<T>): Promise<T>;
+}

package/dist/logger.js

@@ -0,0 +1,56 @@
+/**
+ * Logger that prints plain text locally and GitHub Actions workflow commands in CI.
+ */
+export class Logger {
+    ci;
+    quiet;
+    verbose;
+    stdout;
+    stderr;
+    constructor({ ci = 'true' === process.env.GITHUB_ACTIONS, quiet = false, verbose = false, stdout = process.stdout, stderr = process.stderr, } = {}) {
+        this.ci = ci;
+        this.quiet = quiet;
+        this.verbose = verbose;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+    info(message) {
+        if (!this.quiet) {
+            this.stdout.write(`${message}\n`);
+        }
+    }
+    debug(message) {
+        if (this.verbose && !this.quiet) {
+            this.stdout.write(this.ci ? `::debug::${message}\n` : `${message}\n`);
+        }
+    }
+    notice(message) {
+        if (!this.quiet) {
+            this.stdout.write(this.ci ? `::notice::${message}\n` : `${message}\n`);
+        }
+    }
+    warning(message) {
+        this.stderr.write(this.ci ? `::warning::${message}\n` : `Warning: ${message}\n`);
+    }
+    error(message) {
+        this.stderr.write(this.ci ? `::error::${message}\n` : `Error: ${message}\n`);
+    }
+    /**
+     * Run a callback inside a collapsible log group.
+     *
+     * @param title    Group title.
+     * @param callback Callback to run inside the group.
+     * @return Callback result.
+     */
+    async group(title, callback) {
+        this.info(this.ci ? `::group::${title}` : `== ${title}`);
+        try {
+            return await callback();
+        }
+        finally {
+            if (this.ci) {
+                this.info('::endgroup::');
+            }
+        }
+    }
+}

package/dist/package-meta.d.ts

@@ -0,0 +1,112 @@
+import type { PackageType } from './checksums.ts';
+/**
+ * Number of bytes that WordPress reads from a file to parse its headers.
+ */
+export declare const HEADER_BYTES = 8192;
+/**
+ * Headers of the main plugin file, as read by get_plugin_data().
+ */
+export declare const PLUGIN_HEADERS: readonly ["Plugin Name", "Plugin URI", "Version", "Description", "Author", "Author URI", "Text Domain", "Domain Path", "Network", "Requires at least", "Requires PHP", "Requires Plugins", "Update URI", "License", "License URI"];
+/**
+ * Headers of the theme style.css, as read by wp_get_theme().
+ */
+export declare const THEME_HEADERS: readonly ["Theme Name", "Theme URI", "Description", "Author", "Author URI", "Version", "Template", "Status", "Tags", "Text Domain", "Domain Path", "Requires at least", "Tested up to", "Requires PHP", "License", "License URI"];
+/**
+ * Headers at the top of readme.txt and readme.md, as read by the
+ * WordPress.org readme parser.
+ */
+export declare const README_HEADERS: readonly ["Contributors", "Donate link", "Tags", "Requires at least", "Tested up to", "Requires PHP", "Stable tag", "License", "License URI"];
+/**
+ * Readme file names that WordPress.org reads, in order of preference.
+ */
+export declare const README_FILENAMES: string[];
+/**
+ * Header values keyed by the header name as listed in PLUGIN_HEADERS,
+ * THEME_HEADERS or README_HEADERS. Missing and empty headers are left out.
+ */
+export type HeaderValues = Record<string, string>;
+export interface ParseFileHeadersInput {
+    /** File contents, usually the first HEADER_BYTES bytes. */
+    contents: string;
+    /** Header names to read. */
+    headers: readonly string[];
+}
+export interface ReadmeMeta {
+    /** Readme path relative to the package directory. */
+    file: string;
+    /** Readme headers like Stable tag and Tested up to. */
+    headers: HeaderValues;
+}
+/**
+ * Plugin or theme details read from its files.
+ */
+export interface PackageMeta {
+    /** Package type. */
+    type: PackageType;
+    /** Main plugin file or style.css, relative to the package directory. */
+    mainFile: string;
+    /** Headers of the main file. */
+    headers: HeaderValues;
+    /** Version header, or null when it's missing. */
+    version: string | null;
+    /** Readme details, or null without a readme. */
+    readme: ReadmeMeta | null;
+}
+export interface FindMainPluginFileInput {
+    /** Plugin directory. */
+    dir: string;
+    /** Plugin slug, to prefer {slug}.php when several files have headers. */
+    slug?: string | null;
+}
+export interface ReadPackageMetaInput {
+    /** Plugin or theme directory. */
+    dir: string;
+    /** Plugin slug, to prefer {slug}.php when several files have headers. */
+    slug?: string | null;
+    /** Readme file name, defaults to the first of README_FILENAMES that exists. */
+    readme?: string | null;
+}
+/**
+ * Parse WordPress file headers like "Version: 1.2.0" from a PHP or CSS file
+ * comment, the same way as get_file_data() in WordPress: a header can be on
+ * any line, after comment characters, and the value ends at the line end or
+ * a closing comment.
+ *
+ * @param input File contents and the headers to read.
+ * @return Non-empty header values.
+ */
+export declare function parseFileHeaders(input: ParseFileHeadersInput): HeaderValues;
+/**
+ * Parse the headers of a readme.txt or readme.md, the "Key: value" lines
+ * between the title and the first section. Markdown emphasis around the
+ * names, like "**Stable tag:** 1.2.0", is ignored.
+ *
+ * @param contents Readme contents.
+ * @return Non-empty header values keyed by the names in README_HEADERS.
+ */
+export declare function parseReadmeHeaders(contents: string): HeaderValues;
+/**
+ * Read the start of a file, where WordPress looks for the headers.
+ *
+ * @param path File path.
+ * @return The first HEADER_BYTES bytes as text, or null when the file doesn't exist.
+ */
+export declare function readFileStart(path: string): Promise<string | null>;
+/**
+ * Find the main plugin file: a top-level .php file with a "Plugin Name"
+ * header in its first 8 KB, like WordPress does. When several files have the
+ * header, {slug}.php wins, then the first file by name.
+ *
+ * @param input Plugin directory and slug.
+ * @return File name, or null when there's no plugin file.
+ */
+export declare function findMainPluginFile(input: FindMainPluginFileInput): Promise<string | null>;
+/**
+ * Read the plugin or theme headers and readme of a directory. A directory
+ * with a main plugin file is a plugin, otherwise one with a "Theme Name" in
+ * style.css is a theme.
+ *
+ * @param input Directory, slug and readme name.
+ * @return Package details, or null when the directory has neither.
+ */
+export declare function readPackageMeta(input: ReadPackageMetaInput): Promise<PackageMeta | null>;

package/dist/package-meta.js

@@ -0,0 +1,222 @@
+import { open, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isErrorCode } from "./file-selection.js";
+/**
+ * Number of bytes that WordPress reads from a file to parse its headers.
+ */
+export const HEADER_BYTES = 8192;
+/**
+ * Headers of the main plugin file, as read by get_plugin_data().
+ */
+export const PLUGIN_HEADERS = [
+    'Plugin Name',
+    'Plugin URI',
+    'Version',
+    'Description',
+    'Author',
+    'Author URI',
+    'Text Domain',
+    'Domain Path',
+    'Network',
+    'Requires at least',
+    'Requires PHP',
+    'Requires Plugins',
+    'Update URI',
+    'License',
+    'License URI',
+];
+/**
+ * Headers of the theme style.css, as read by wp_get_theme().
+ */
+export const THEME_HEADERS = [
+    'Theme Name',
+    'Theme URI',
+    'Description',
+    'Author',
+    'Author URI',
+    'Version',
+    'Template',
+    'Status',
+    'Tags',
+    'Text Domain',
+    'Domain Path',
+    'Requires at least',
+    'Tested up to',
+    'Requires PHP',
+    'License',
+    'License URI',
+];
+/**
+ * Headers at the top of readme.txt and readme.md, as read by the
+ * WordPress.org readme parser.
+ */
+export const README_HEADERS = [
+    'Contributors',
+    'Donate link',
+    'Tags',
+    'Requires at least',
+    'Tested up to',
+    'Requires PHP',
+    'Stable tag',
+    'License',
+    'License URI',
+];
+/**
+ * Readme file names that WordPress.org reads, in order of preference.
+ */
+export const README_FILENAMES = ['readme.txt', 'readme.md'];
+/**
+ * Parse WordPress file headers like "Version: 1.2.0" from a PHP or CSS file
+ * comment, the same way as get_file_data() in WordPress: a header can be on
+ * any line, after comment characters, and the value ends at the line end or
+ * a closing comment.
+ *
+ * @param input File contents and the headers to read.
+ * @return Non-empty header values.
+ */
+export function parseFileHeaders(input) {
+    const contents = input.contents.replace(/\r\n?/g, '\n');
+    const entries = input.headers.map((header) => [
+        header,
+        matchFileHeader(contents, header),
+    ]);
+    return Object.fromEntries(entries.filter(([, value]) => value));
+}
+function matchFileHeader(contents, header) {
+    const pattern = new RegExp(`^(?:[ \\t]*<\\?php)?[ \\t/*#@]*${escapeRegExp(header)}:(.*)$`, 'mi');
+    const value = pattern.exec(contents)?.[1] ?? '';
+    return value.replace(/\s*(?:\*\/|\?>).*/, '').trim();
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Parse the headers of a readme.txt or readme.md, the "Key: value" lines
+ * between the title and the first section. Markdown emphasis around the
+ * names, like "**Stable tag:** 1.2.0", is ignored.
+ *
+ * @param contents Readme contents.
+ * @return Non-empty header values keyed by the names in README_HEADERS.
+ */
+export function parseReadmeHeaders(contents) {
+    const lines = contents.replace(/\r\n?/g, '\n').split('\n');
+    const firstSection = lines.findIndex((line, index) => index > 0 && /^\s*(==|##)/.test(line));
+    const headerLines = lines.slice(0, -1 === firstSection ? lines.length : firstSection);
+    const values = {};
+    headerLines.forEach((line) => {
+        const match = /^[\s*_-]*([^:*_]+?)[*_]*\s*:[*_]*\s*(.*?)\s*$/.exec(line);
+        const header = README_HEADERS.find((name) => name.toLowerCase() === match?.[1]?.toLowerCase());
+        if (header && match?.[2] && !Object.hasOwn(values, header)) {
+            values[header] = match[2];
+        }
+    });
+    return values;
+}
+/**
+ * Read the start of a file, where WordPress looks for the headers.
+ *
+ * @param path File path.
+ * @return The first HEADER_BYTES bytes as text, or null when the file doesn't exist.
+ */
+export async function readFileStart(path) {
+    const handle = await open(path, 'r').catch((error) => {
+        if (isErrorCode(error, 'ENOENT')) {
+            return null;
+        }
+        throw error;
+    });
+    if (!handle) {
+        return null;
+    }
+    try {
+        const buffer = Buffer.alloc(HEADER_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEADER_BYTES, 0);
+        return buffer.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Find the main plugin file: a top-level .php file with a "Plugin Name"
+ * header in its first 8 KB, like WordPress does. When several files have the
+ * header, {slug}.php wins, then the first file by name.
+ *
+ * @param input Plugin directory and slug.
+ * @return File name, or null when there's no plugin file.
+ */
+export async function findMainPluginFile(input) {
+    const { dir, slug } = input;
+    const entries = await readdir(dir, { withFileTypes: true });
+    const phpFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.php'))
+        .map((entry) => entry.name)
+        .sort();
+    const candidates = await Promise.all(phpFiles.map(async (file) => {
+        const contents = await readFileStart(join(dir, file));
+        const headers = parseFileHeaders({
+            contents: contents ?? '',
+            headers: ['Plugin Name'],
+        });
+        return headers['Plugin Name'] ? file : null;
+    }));
+    const pluginFiles = candidates.filter((file) => null !== file);
+    return (pluginFiles.find((file) => `${slug}.php` === file) ??
+        pluginFiles.at(0) ??
+        null);
+}
+/**
+ * Read the plugin or theme headers and readme of a directory. A directory
+ * with a main plugin file is a plugin, otherwise one with a "Theme Name" in
+ * style.css is a theme.
+ *
+ * @param input Directory, slug and readme name.
+ * @return Package details, or null when the directory has neither.
+ */
+export async function readPackageMeta(input) {
+    const { dir } = input;
+    const pluginFile = await findMainPluginFile(input);
+    const mainFile = pluginFile ?? 'style.css';
+    const type = pluginFile ? 'plugin' : 'theme';
+    const headers = parseFileHeaders({
+        contents: (await readFileStart(join(dir, mainFile))) ?? '',
+        headers: pluginFile ? PLUGIN_HEADERS : THEME_HEADERS,
+    });
+    if (pluginFile || headers['Theme Name']) {
+        return {
+            type,
+            mainFile,
+            headers,
+            version: headers.Version ?? null,
+            readme: await readReadme(dir, input.readme),
+        };
+    }
+    return null;
+}
+/**
+ * Read the readme headers.
+ *
+ * @param dir  Package directory.
+ * @param name Readme file name, or the default names when not set.
+ * @return Readme details, or null when there's no readme.
+ */
+async function readReadme(dir, name) {
+    const names = name ? [name] : README_FILENAMES;
+    const readmes = await Promise.all(names.map(async (file) => ({
+        file,
+        contents: await readFile(join(dir, file), 'utf8').catch((error) => {
+            if (isErrorCode(error, 'ENOENT')) {
+                return null;
+            }
+            throw error;
+        }),
+    })));
+    const readme = readmes.find(({ contents }) => null !== contents);
+    if (readme) {
+        return {
+            file: readme.file,
+            headers: parseReadmeHeaders(readme.contents ?? ''),
+        };
+    }
+    return null;
+}