@wpelevator/wp-release 0.0.0-stage → 0.1.1

package/dist/svn-deploy.d.ts

@@ -0,0 +1,208 @@
+import { Logger } from './logger.ts';
+import type { DeployOptions } from './deploy-options.ts';
+import type { PackageMeta } from './package-meta.ts';
+import { Svn } from './svn.ts';
+import type { SvnStatusEntry } from './svn.ts';
+/**
+ * MIME types of the plugin directory asset formats. svn guesses binary
+ * types, but WordPress.org serves assets with the svn:mime-type property,
+ * so it's set explicitly. WordPress.org documents PNG, JPEG and GIF images
+ * and SVG icons; other formats keep the type svn assigns.
+ */
+export declare const ASSET_MIME_TYPES: Record<string, string>;
+/**
+ * Result of a deploy.
+ */
+export interface DeployResult {
+    /** Whether an SVN commit was made. */
+    committed: boolean;
+    /** SVN revision of the commit, null when nothing was committed. */
+    revision: number | null;
+    /** Deployed version, null when it's unknown, like for assets-only runs. */
+    version: string | null;
+    /** Changed paths in the working copy, relative to the repository root. */
+    changes: SvnStatusEntry[];
+}
+/**
+ * Working copy path to update after the sparse checkout.
+ */
+export interface CheckoutPath {
+    path: string;
+    depth: 'immediates' | 'infinity';
+}
+/**
+ * Deploy a plugin to the WordPress.org plugin SVN repository.
+ *
+ * Each step is a separate method so that CI wrappers can run and report them
+ * one by one, in order: prepare(), checkVersions(), checkout(), sync() and
+ * commit(), followed by cleanup() in a finally block. The steps share the
+ * temporary working copy on the instance. run() does all of it, or nothing
+ * when there's nothing to write.
+ */
+export declare class SvnDeploy {
+    readonly options: DeployOptions;
+    readonly logger: Logger;
+    readonly svn: Svn;
+    /** Temporary directory with the working copy and extracted ZIP. */
+    tempDir: string | null;
+    /** Directory with the plugin files to deploy. */
+    filesDir: string | null;
+    /** Deployed version, from the options or the Version header. */
+    version: string | null;
+    /** Working copy changes after sync(). */
+    changes: SvnStatusEntry[];
+    /**
+     * @param options Options from resolveDeployOptions().
+     * @param logger  Logger instance.
+     * @param svn     SVN client, with the credentials from the options by default.
+     */
+    constructor(options: DeployOptions, logger?: Logger, svn?: Svn);
+    /**
+     * Get the working copy path.
+     *
+     * @return Absolute path.
+     * @throws {Error} Before prepare().
+     */
+    getWorkingCopy(): string;
+    /**
+     * Create the temporary directory and, with fromZip, extract the archive
+     * into it after checking that every entry is safe and inside the {slug}/
+     * root folder.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Check the plugin files before anything is written. A trunk sync needs
+     * a plugin with a Version header that matches the version, and with an
+     * SVN tag also a readme Stable tag that matches. Readme-only updates need
+     * the readme.
+     *
+     * @throws {ValidationError} When the files or versions don't match.
+     */
+    checkVersions(): Promise<void>;
+    /**
+     * Read the plugin headers of the files to deploy.
+     *
+     * @param  sourceDir Directory with the plugin files.
+     * @return Plugin metadata.
+     * @throws {ValidationError} If the directory isn't a plugin.
+     */
+    readPluginMeta(sourceDir: string): Promise<PackageMeta>;
+    /**
+     * Create a sparse checkout with only the directories the flags write to,
+     * creating the ones that don't exist in the repository yet.
+     *
+     * @throws {ValidationError} If the SVN tag exists and force isn't set.
+     */
+    checkout(): Promise<void>;
+    /**
+     * Create and add a top-level directory that's missing from the repository,
+     * like assets/ in a new plugin repository.
+     *
+     * @param path Path relative to the working copy.
+     */
+    addMissingDirectory(path: string): Promise<void>;
+    /**
+     * Check if the SVN tag exists in the working copy.
+     *
+     * @return Whether tags/<version> exists.
+     */
+    hasTag(): boolean;
+    /**
+     * Copy the files for each write flag into the working copy and stage
+     * additions, deletions and asset MIME types, then copy trunk to the tag.
+     */
+    sync(): Promise<void>;
+    /**
+     * List the plugin files to deploy. Files from a ZIP are already selected,
+     * so the ignore file and exclude patterns only apply to a directory;
+     * version control metadata is left out of both.
+     *
+     * @param sourceDir Directory with the plugin files.
+     * @return Relative file paths.
+     */
+    getSourceFiles(sourceDir: string): Promise<string[]>;
+    /**
+     * Sync every file of the assets directory to assets/.
+     */
+    syncAssets(): Promise<void>;
+    /**
+     * Add unversioned files and remove missing ones in svn.
+     */
+    stage(): Promise<void>;
+    /**
+     * Set svn:mime-type on the asset images, grouped by type.
+     */
+    setAssetMimeTypes(): Promise<void>;
+    /**
+     * Copy trunk to the SVN tag, replacing an existing tag with force.
+     */
+    copyTag(): Promise<void>;
+    /**
+     * Commit the working copy unless there are no changes or this is a dry
+     * run. Credentials are only needed here, and not for file:// URLs.
+     *
+     * @return Deploy result.
+     * @throws {CredentialsError} Without a username and password.
+     */
+    commit(): Promise<DeployResult>;
+    /**
+     * Check that the SVN client has the credentials for a commit.
+     *
+     * @throws {CredentialsError} Without a username and password.
+     */
+    checkCredentials(): void;
+    /**
+     * Remove the temporary working copy and extracted files.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Run all steps in order, or nothing when there is nothing to write.
+     *
+     * @return Deploy result.
+     */
+    run(): Promise<DeployResult>;
+    /**
+     * Describe the SVN changes that the write flags ask for.
+     *
+     * @return Planned changes, in order.
+     */
+    getPlan(): string[];
+    /**
+     * Get the working copy paths to update after the sparse checkout. Tags
+     * only need their directory listing to check for an existing version.
+     *
+     * @return Relative paths with their SVN checkout depth.
+     */
+    getCheckoutPaths(): CheckoutPath[];
+    /**
+     * Check if anything will be written to SVN.
+     *
+     * @return Whether to check out and commit.
+     */
+    hasWrites(): boolean;
+    /**
+     * Check if the deploy reads plugin files, which assets-only runs don't.
+     *
+     * @return Whether trunk or the readme is written.
+     */
+    needsFiles(): boolean;
+    /**
+     * Describe the files that are synced, including the ignore rules.
+     *
+     * @return Source description for the log.
+     */
+    describeSource(): string;
+    /**
+     * Describe the ignore file and exclude patterns applied to the source.
+     *
+     * @return Rules description, empty without rules.
+     */
+    describeRules(): string;
+    /**
+     * Get the path of the tag in the working copy.
+     *
+     * @return Relative path, or null without a tag.
+     */
+    getTagPath(): string | null;
+    getDefaultMessage(): string;
+}

package/dist/svn-deploy.js

@@ -0,0 +1,485 @@
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, join, posix } from 'node:path';
+import ignore from 'ignore';
+import { Logger } from "./logger.js";
+import { getDeployOptionWarnings } from "./deploy-options.js";
+import { CredentialsError, ValidationError } from "./errors.js";
+import { loadFileRules, selectFiles } from "./file-selection.js";
+import { readPackageMeta } from "./package-meta.js";
+import { Svn } from "./svn.js";
+import { copyFileIfChanged, syncDirectory } from "./sync.js";
+import { extractZip } from "./unzip.js";
+import { findVersionMismatches } from "./version-check.js";
+/**
+ * MIME types of the plugin directory asset formats. svn guesses binary
+ * types, but WordPress.org serves assets with the svn:mime-type property,
+ * so it's set explicitly. WordPress.org documents PNG, JPEG and GIF images
+ * and SVG icons; other formats keep the type svn assigns.
+ */
+export const ASSET_MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+};
+/**
+ * Deploy a plugin to the WordPress.org plugin SVN repository.
+ *
+ * Each step is a separate method so that CI wrappers can run and report them
+ * one by one, in order: prepare(), checkVersions(), checkout(), sync() and
+ * commit(), followed by cleanup() in a finally block. The steps share the
+ * temporary working copy on the instance. run() does all of it, or nothing
+ * when there's nothing to write.
+ */
+export class SvnDeploy {
+    options;
+    logger;
+    svn;
+    /** Temporary directory with the working copy and extracted ZIP. */
+    tempDir = null;
+    /** Directory with the plugin files to deploy. */
+    filesDir = null;
+    /** Deployed version, from the options or the Version header. */
+    version = null;
+    /** Working copy changes after sync(). */
+    changes = [];
+    /**
+     * @param options Options from resolveDeployOptions().
+     * @param logger  Logger instance.
+     * @param svn     SVN client, with the credentials from the options by default.
+     */
+    constructor(options, logger = new Logger(), svn) {
+        this.options = options;
+        this.logger = logger;
+        this.version = options.version;
+        this.svn =
+            svn ??
+                new Svn({
+                    username: options.svnUsername,
+                    password: options.svnPassword,
+                    logger,
+                });
+    }
+    /**
+     * Get the working copy path.
+     *
+     * @return Absolute path.
+     * @throws {Error} Before prepare().
+     */
+    getWorkingCopy() {
+        if (!this.tempDir) {
+            throw new Error('Call prepare() before the other deploy steps.');
+        }
+        return join(this.tempDir, 'svn');
+    }
+    /**
+     * Create the temporary directory and, with fromZip, extract the archive
+     * into it after checking that every entry is safe and inside the {slug}/
+     * root folder.
+     */
+    async prepare() {
+        const { fromZip, sourceDir, slug } = this.options;
+        this.tempDir = await mkdtemp(join(tmpdir(), `wp-release-${slug}-`));
+        this.filesDir = sourceDir;
+        if (fromZip && this.needsFiles()) {
+            this.filesDir = join(this.tempDir, 'files');
+            await mkdir(this.filesDir);
+            await extractZip({
+                zipPath: fromZip,
+                targetDir: this.filesDir,
+                rootFolder: slug,
+            });
+        }
+    }
+    /**
+     * Check the plugin files before anything is written. A trunk sync needs
+     * a plugin with a Version header that matches the version, and with an
+     * SVN tag also a readme Stable tag that matches. Readme-only updates need
+     * the readme.
+     *
+     * @throws {ValidationError} When the files or versions don't match.
+     */
+    async checkVersions() {
+        const { trunk, readmeOnly, svnTag, slug, readme } = this.options;
+        const sourceDir = this.filesDir ?? this.options.sourceDir;
+        if (trunk || readmeOnly) {
+            const meta = await this.readPluginMeta(sourceDir);
+            if (readmeOnly && !meta.readme) {
+                throw new ValidationError(`${readme} doesn't exist in ${sourceDir}.`);
+            }
+            if (trunk) {
+                const { version, mismatches } = await findVersionMismatches({
+                    sourceDir,
+                    meta,
+                    slug,
+                    version: this.options.version,
+                    stableTag: Boolean(svnTag),
+                });
+                this.version = version;
+                if (mismatches.length) {
+                    throw new ValidationError(mismatches
+                        .map(({ message }) => message)
+                        .join('\n'));
+                }
+                this.logger.info(`Deploying version ${version}.`);
+            }
+        }
+    }
+    /**
+     * Read the plugin headers of the files to deploy.
+     *
+     * @param  sourceDir Directory with the plugin files.
+     * @return Plugin metadata.
+     * @throws {ValidationError} If the directory isn't a plugin.
+     */
+    async readPluginMeta(sourceDir) {
+        const { slug, readme } = this.options;
+        const meta = await readPackageMeta({ dir: sourceDir, slug, readme });
+        if ('theme' === meta?.type) {
+            throw new ValidationError(`${sourceDir} is a theme. Themes are released by uploading a ZIP on WordPress.org, use "wp-release zip".`);
+        }
+        if (!meta) {
+            throw new ValidationError(`No main plugin file with a Plugin Name header in ${sourceDir}.`);
+        }
+        return meta;
+    }
+    /**
+     * Create a sparse checkout with only the directories the flags write to,
+     * creating the ones that don't exist in the repository yet.
+     *
+     * @throws {ValidationError} If the SVN tag exists and force isn't set.
+     */
+    async checkout() {
+        const workingCopy = this.getWorkingCopy();
+        const tagPath = this.getTagPath();
+        await this.svn.checkout({
+            url: this.options.svnUrl,
+            path: workingCopy,
+            depth: 'immediates',
+        });
+        for (const { path, depth } of this.getCheckoutPaths()) {
+            await this.svn.update({ path: join(workingCopy, path), depth });
+            await this.addMissingDirectory(path);
+        }
+        if (tagPath && !this.options.force && this.hasTag()) {
+            throw new ValidationError(`${tagPath} already exists in ${this.options.svnUrl}. Pass --force to replace it.`);
+        }
+    }
+    /**
+     * Create and add a top-level directory that's missing from the repository,
+     * like assets/ in a new plugin repository.
+     *
+     * @param path Path relative to the working copy.
+     */
+    async addMissingDirectory(path) {
+        const workingCopy = this.getWorkingCopy();
+        if (!existsSync(join(workingCopy, path))) {
+            await mkdir(join(workingCopy, path));
+            await this.svn.add({ paths: [path], cwd: workingCopy });
+        }
+    }
+    /**
+     * Check if the SVN tag exists in the working copy.
+     *
+     * @return Whether tags/<version> exists.
+     */
+    hasTag() {
+        const tagPath = this.getTagPath();
+        return Boolean(tagPath && existsSync(join(this.getWorkingCopy(), tagPath)));
+    }
+    /**
+     * Copy the files for each write flag into the working copy and stage
+     * additions, deletions and asset MIME types, then copy trunk to the tag.
+     */
+    async sync() {
+        const { trunk, readmeOnly, assets, readme } = this.options;
+        const workingCopy = this.getWorkingCopy();
+        const sourceDir = this.filesDir ?? this.options.sourceDir;
+        if (trunk) {
+            await syncDirectory({
+                sourceDir,
+                files: await this.getSourceFiles(sourceDir),
+                targetDir: join(workingCopy, 'trunk'),
+            });
+        }
+        if (readmeOnly) {
+            await copyFileIfChanged(join(sourceDir, readme), join(workingCopy, 'trunk', readme));
+        }
+        if (assets) {
+            await this.syncAssets();
+        }
+        await this.stage();
+        if (assets) {
+            await this.setAssetMimeTypes();
+        }
+        await this.copyTag();
+        this.changes = await this.svn.status(workingCopy);
+    }
+    /**
+     * List the plugin files to deploy. Files from a ZIP are already selected,
+     * so the ignore file and exclude patterns only apply to a directory;
+     * version control metadata is left out of both.
+     *
+     * @param sourceDir Directory with the plugin files.
+     * @return Relative file paths.
+     */
+    async getSourceFiles(sourceDir) {
+        const rules = await loadFileRules(this.options.fromZip ? {} : this.options);
+        return selectFiles(sourceDir, rules);
+    }
+    /**
+     * Sync every file of the assets directory to assets/.
+     */
+    async syncAssets() {
+        const assetsDir = this.options.assetsDir ?? '';
+        await syncDirectory({
+            sourceDir: assetsDir,
+            files: await selectFiles(assetsDir, await loadFileRules({})),
+            targetDir: join(this.getWorkingCopy(), 'assets'),
+        });
+    }
+    /**
+     * Add unversioned files and remove missing ones in svn.
+     */
+    async stage() {
+        const workingCopy = this.getWorkingCopy();
+        const status = await this.svn.status(workingCopy);
+        const pathsWith = (type) => status
+            .filter((entry) => type === entry.status)
+            .map(({ path }) => path);
+        await this.svn.add({
+            paths: pathsWith('unversioned'),
+            cwd: workingCopy,
+        });
+        await this.svn.remove({
+            paths: pathsWith('missing'),
+            cwd: workingCopy,
+        });
+    }
+    /**
+     * Set svn:mime-type on the asset images, grouped by type.
+     */
+    async setAssetMimeTypes() {
+        const workingCopy = this.getWorkingCopy();
+        const files = await selectFiles(join(workingCopy, 'assets'), ignore().add('.svn/'));
+        for (const [extension, mimeType] of Object.entries(ASSET_MIME_TYPES)) {
+            await this.svn.propset({
+                name: 'svn:mime-type',
+                value: mimeType,
+                paths: files
+                    .filter((file) => extension === extname(file).toLowerCase())
+                    .map((file) => posix.join('assets', file)),
+                cwd: workingCopy,
+            });
+        }
+    }
+    /**
+     * Copy trunk to the SVN tag, replacing an existing tag with force.
+     */
+    async copyTag() {
+        const tagPath = this.getTagPath();
+        const workingCopy = this.getWorkingCopy();
+        if (tagPath && this.hasTag()) {
+            this.logger.warning(`Replacing the existing ${tagPath}.`);
+            await this.svn.remove({ paths: [tagPath], cwd: workingCopy });
+        }
+        if (tagPath) {
+            await this.svn.copy({
+                from: 'trunk',
+                to: tagPath,
+                cwd: workingCopy,
+            });
+        }
+    }
+    /**
+     * Commit the working copy unless there are no changes or this is a dry
+     * run. Credentials are only needed here, and not for file:// URLs.
+     *
+     * @return Deploy result.
+     * @throws {CredentialsError} Without a username and password.
+     */
+    async commit() {
+        const { changes, version } = this;
+        const result = { committed: false, revision: null, version, changes };
+        if (!changes.length) {
+            this.logger.notice('No changes to commit.');
+            return result;
+        }
+        await this.logger.group('SVN status', () => changes.forEach(({ status, path }) => this.logger.info(`${status.padEnd(12)}${path}`)));
+        if (this.options.dryRun) {
+            this.logger.notice(`Dry run, skipped committing ${changes.length} changes.`);
+            return result;
+        }
+        this.checkCredentials();
+        const revision = await this.svn.commit({
+            path: this.getWorkingCopy(),
+            message: this.options.message ?? this.getDefaultMessage(),
+        });
+        this.logger.notice(`Committed revision ${revision}.`);
+        return { ...result, committed: true, revision };
+    }
+    /**
+     * Check that the SVN client has the credentials for a commit.
+     *
+     * @throws {CredentialsError} Without a username and password.
+     */
+    checkCredentials() {
+        const { svnUrl } = this.options;
+        const { username, password } = this.svn;
+        if (!svnUrl.startsWith('file://') && !(username && password)) {
+            throw new CredentialsError(`Committing to ${svnUrl} needs SVN credentials. Set SVN_USERNAME and SVN_PASSWORD, or use --dry-run.`);
+        }
+    }
+    /**
+     * Remove the temporary working copy and extracted files.
+     */
+    async cleanup() {
+        if (this.tempDir) {
+            await rm(this.tempDir, { recursive: true, force: true });
+            this.tempDir = null;
+        }
+    }
+    /**
+     * Run all steps in order, or nothing when there is nothing to write.
+     *
+     * @return Deploy result.
+     */
+    async run() {
+        if (this.hasWrites()) {
+            getDeployOptionWarnings(this.options).forEach((warning) => this.logger.warning(warning));
+            await this.logger.group('Planned changes', () => this.getPlan().forEach((step) => this.logger.info(step)));
+            try {
+                await this.prepare();
+                await this.checkVersions();
+                await this.checkout();
+                await this.sync();
+                return await this.commit();
+            }
+            finally {
+                await this.cleanup();
+            }
+        }
+        this.logger.notice('Nothing to deploy.');
+        return {
+            committed: false,
+            revision: null,
+            version: this.version,
+            changes: [],
+        };
+    }
+    /**
+     * Describe the SVN changes that the write flags ask for.
+     *
+     * @return Planned changes, in order.
+     */
+    getPlan() {
+        const { svnUrl, trunk, readmeOnly, assets, assetsDir, readme, force } = this.options;
+        const tagPath = this.getTagPath();
+        const message = this.options.message ?? this.getDefaultMessage();
+        const plan = [
+            `Check out ${svnUrl} with ${this.getCheckoutPaths()
+                .map(({ path }) => path)
+                .join(', ')}`,
+            tagPath && !force && `Stop if ${tagPath} already exists`,
+            tagPath && force && `Replace ${tagPath} if it exists`,
+            trunk && `Sync ${this.describeSource()} to trunk/`,
+            readmeOnly && `Copy ${readme} to trunk/`,
+            tagPath && `Copy trunk/ to ${tagPath}`,
+            assets && `Sync ${assetsDir} to assets/`,
+            this.options.dryRun
+                ? `Skip the commit "${message}" (dry run)`
+                : `Commit "${message}"`,
+        ];
+        return plan.filter((step) => Boolean(step));
+    }
+    /**
+     * Get the working copy paths to update after the sparse checkout. Tags
+     * only need their directory listing to check for an existing version.
+     *
+     * @return Relative paths with their SVN checkout depth.
+     */
+    getCheckoutPaths() {
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
+        const paths = [];
+        if (trunk || readmeOnly) {
+            paths.push({ path: 'trunk', depth: 'infinity' });
+        }
+        if (svnTag) {
+            paths.push({ path: 'tags', depth: 'immediates' });
+        }
+        if (assets) {
+            paths.push({ path: 'assets', depth: 'infinity' });
+        }
+        return paths;
+    }
+    /**
+     * Check if anything will be written to SVN.
+     *
+     * @return Whether to check out and commit.
+     */
+    hasWrites() {
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
+        return Boolean(trunk || readmeOnly || svnTag || assets);
+    }
+    /**
+     * Check if the deploy reads plugin files, which assets-only runs don't.
+     *
+     * @return Whether trunk or the readme is written.
+     */
+    needsFiles() {
+        return this.options.trunk || this.options.readmeOnly;
+    }
+    /**
+     * Describe the files that are synced, including the ignore rules.
+     *
+     * @return Source description for the log.
+     */
+    describeSource() {
+        const { fromZip, sourceDir } = this.options;
+        if (fromZip) {
+            return fromZip;
+        }
+        const rules = this.describeRules();
+        return rules ? `${sourceDir} (${rules})` : sourceDir;
+    }
+    /**
+     * Describe the ignore file and exclude patterns applied to the source.
+     *
+     * @return Rules description, empty without rules.
+     */
+    describeRules() {
+        const { distignore, exclude } = this.options;
+        const rules = [
+            distignore && `rules from ${distignore}`,
+            exclude.length > 0 && `excluding ${exclude.join(', ')}`,
+        ];
+        return rules.filter(Boolean).join(', ');
+    }
+    /**
+     * Get the path of the tag in the working copy.
+     *
+     * @return Relative path, or null without a tag.
+     */
+    getTagPath() {
+        const { svnTag } = this.options;
+        if (svnTag) {
+            return `tags/${svnTag}`;
+        }
+        return null;
+    }
+    getDefaultMessage() {
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
+        if (svnTag) {
+            return `Release version ${svnTag}`;
+        }
+        const parts = [
+            trunk && 'trunk',
+            readmeOnly && 'readme',
+            assets && 'assets',
+        ];
+        return `Update ${parts.filter(Boolean).join(' and ')}`;
+    }
+}