@wpelevator/wp-release 0.0.0-stage → 0.1.0

package/dist/svn.d.ts

@@ -0,0 +1,209 @@
+import type { Logger } from './logger.ts';
+export interface SvnCommandInput {
+    /** Arguments after "svn", passed without a shell. */
+    args: string[];
+    /** Working directory of the command. */
+    cwd?: string;
+    /** Text written to the standard input, like the password. */
+    input?: string;
+}
+export interface SvnCommandOutput {
+    /** Standard output. */
+    stdout: string;
+    /** Standard error. */
+    stderr: string;
+}
+/**
+ * Run an svn command. Rejects with an SvnError when it exits with an error.
+ */
+export type SvnRunner = (input: SvnCommandInput) => Promise<SvnCommandOutput>;
+export type SvnDepth = 'empty' | 'files' | 'immediates' | 'infinity';
+/**
+ * Status of a working copy path, from the first two columns of svn status.
+ */
+export type SvnStatusType = 'added' | 'modified' | 'deleted' | 'replaced' | 'missing' | 'unversioned' | 'conflicted' | 'obstructed';
+export interface SvnStatusEntry {
+    /** Status of the path. */
+    status: SvnStatusType;
+    /** Path relative to the status path, with forward slashes. */
+    path: string;
+}
+export interface SvnOptions {
+    /** Command runner, createSvnRunner() by default. */
+    runner?: SvnRunner;
+    /** Username for commits. */
+    username?: string | null;
+    /** Password for commits, passed on the standard input. */
+    password?: string | null;
+    /** Logger for the commands, at debug level. */
+    logger?: Logger;
+}
+export interface SvnCheckoutInput {
+    /** Repository URL. */
+    url: string;
+    /** Working copy path. */
+    path: string;
+    /** Checkout depth, immediates by default for a sparse checkout. */
+    depth?: SvnDepth;
+}
+export interface SvnUpdateInput {
+    /** Working copy path. */
+    path: string;
+    /** New sticky depth of the path. */
+    depth: SvnDepth;
+}
+export interface SvnPathsInput {
+    /** Working copy paths. */
+    paths: string[];
+    /** Working directory that relative paths resolve against. */
+    cwd?: string;
+}
+export interface SvnCopyInput {
+    /** Source path or URL. */
+    from: string;
+    /** Target path or URL. */
+    to: string;
+    /** Working directory that relative paths resolve against. */
+    cwd?: string;
+}
+export interface SvnPropsetInput extends SvnPathsInput {
+    /** Property name, like svn:mime-type. */
+    name: string;
+    /** Property value. */
+    value: string;
+}
+export interface SvnCommitInput {
+    /** Working copy path. */
+    path: string;
+    /** Commit message. */
+    message: string;
+}
+/**
+ * Failed svn command, with exit code 3 for authentication and permission
+ * errors and 1 otherwise.
+ */
+export declare class SvnError extends Error {
+    name: string;
+    exitCode: number;
+    stderr: string;
+    /**
+     * @param message Error message.
+     * @param stderr  Standard error of the command.
+     */
+    constructor(message: string, stderr?: string);
+}
+/**
+ * Escape a path for svn, which reads anything after the last "@" as a peg
+ * revision, so that files like icon@2x.png work.
+ *
+ * @param path Working copy path.
+ * @return Path with a trailing "@" when it contains one.
+ */
+export declare function toSvnPath(path: string): string;
+/**
+ * Create a runner that spawns the svn binary with an argument array, never
+ * through a shell. Messages are in English so that they can be parsed.
+ *
+ * @param binary Path or name of the svn binary.
+ * @return Command runner.
+ */
+export declare function createSvnRunner(binary?: string): SvnRunner;
+/**
+ * Parse the output of svn status.
+ *
+ * @param stdout Output of svn status.
+ * @return Changed paths with their status, in output order.
+ */
+export declare function parseStatus(stdout: string): SvnStatusEntry[];
+/**
+ * Minimal Subversion client around the svn command line.
+ *
+ * Every command runs non-interactively without caching credentials. The
+ * password is only sent with commits, on the standard input, so it never
+ * appears in the process list or the logs.
+ */
+export declare class Svn {
+    readonly runner: SvnRunner;
+    readonly username: string | null;
+    readonly password: string | null;
+    readonly logger: Logger | null;
+    /**
+     * @param options Runner, credentials and logger.
+     */
+    constructor(options?: SvnOptions);
+    /**
+     * Run an svn subcommand with the global options.
+     *
+     * @param input Arguments, working directory and standard input.
+     * @return Command output.
+     */
+    run(input: SvnCommandInput): Promise<SvnCommandOutput>;
+    /**
+     * Check out a repository, by default with only its top-level directories
+     * so that update() can add the ones that are needed.
+     *
+     * @param input URL, working copy path and depth.
+     */
+    checkout(input: SvnCheckoutInput): Promise<void>;
+    /**
+     * Update a path of a sparse working copy to a new depth.
+     *
+     * @param input Working copy path and depth.
+     */
+    update(input: SvnUpdateInput): Promise<void>;
+    /**
+     * List the entries of a repository directory.
+     *
+     * @param url Repository or working copy path.
+     * @return Entry names, directories with a trailing slash.
+     */
+    list(url: string): Promise<string[]>;
+    /**
+     * Get the changed, unversioned and missing paths of a working copy,
+     * including the files that svn ignores by default.
+     *
+     * @param path Working copy path.
+     * @return Changed paths relative to the working copy.
+     */
+    status(path: string): Promise<SvnStatusEntry[]>;
+    /**
+     * Schedule unversioned paths for addition, including the files that svn
+     * ignores by default and missing parent directories.
+     *
+     * @param input Paths and working directory.
+     */
+    add(input: SvnPathsInput): Promise<void>;
+    /**
+     * Schedule paths for deletion, also when they're already missing.
+     *
+     * @param input Paths and working directory.
+     */
+    remove(input: SvnPathsInput): Promise<void>;
+    /**
+     * Copy a path with its history.
+     *
+     * @param input Source, target and working directory.
+     */
+    copy(input: SvnCopyInput): Promise<void>;
+    /**
+     * Set a property on paths.
+     *
+     * @param input Property name and value, paths and working directory.
+     */
+    propset(input: SvnPropsetInput): Promise<void>;
+    /**
+     * Commit a working copy with the credentials.
+     *
+     * @param input Working copy path and message.
+     * @return Committed revision, or null when there was nothing to commit.
+     */
+    commit(input: SvnCommitInput): Promise<number | null>;
+    /**
+     * Run a subcommand for paths, in batches so that the argument list stays
+     * below the operating system limit.
+     *
+     * @param args  Subcommand and options.
+     * @param input Paths and working directory.
+     */
+    runForPaths(args: string[], input: SvnPathsInput): Promise<void>;
+}

package/dist/svn.js

@@ -0,0 +1,298 @@
+import { spawn } from 'node:child_process';
+import { CredentialsError } from "./errors.js";
+/**
+ * Failed svn command, with exit code 3 for authentication and permission
+ * errors and 1 otherwise.
+ */
+export class SvnError extends Error {
+    name = 'SvnError';
+    exitCode;
+    stderr;
+    /**
+     * @param message Error message.
+     * @param stderr  Standard error of the command.
+     */
+    constructor(message, stderr = '') {
+        super(message);
+        this.stderr = stderr;
+        this.exitCode = isAuthError(stderr) ? CredentialsError.EXIT_CODE : 1;
+    }
+}
+/**
+ * Error codes and messages of failed authentication or missing commit access.
+ */
+const AUTH_ERROR_PATTERN = /E170001|E170013|E175013|E215004|E220003|Authentication failed|Authorization failed|403 Forbidden|401 Unauthorized|Access to .* forbidden/i;
+function isAuthError(stderr) {
+    return AUTH_ERROR_PATTERN.test(stderr);
+}
+/**
+ * Escape a path for svn, which reads anything after the last "@" as a peg
+ * revision, so that files like icon@2x.png work.
+ *
+ * @param path Working copy path.
+ * @return Path with a trailing "@" when it contains one.
+ */
+export function toSvnPath(path) {
+    return path.includes('@') ? `${path}@` : path;
+}
+/**
+ * Create a runner that spawns the svn binary with an argument array, never
+ * through a shell. Messages are in English so that they can be parsed.
+ *
+ * @param binary Path or name of the svn binary.
+ * @return Command runner.
+ */
+export function createSvnRunner(binary = 'svn') {
+    return ({ args, cwd, input }) => new Promise((resolve, reject) => {
+        const child = spawn(binary, args, {
+            cwd,
+            env: { ...process.env, LC_ALL: 'C' },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const output = { stdout: '', stderr: '' };
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (data) => (output.stdout += data));
+        child.stderr.on('data', (data) => (output.stderr += data));
+        child.on('error', (error) => reject(new SvnError(`Can't run ${binary}: ${error.message}. Install the Subversion command line client.`)));
+        child.on('close', (code) => {
+            if (0 === code) {
+                resolve(output);
+            }
+            else {
+                reject(new SvnError(`svn ${args[0]} failed: ${output.stderr.trim()}`, output.stderr));
+            }
+        });
+        child.stdin.end(input ?? '');
+    });
+}
+/**
+ * Parse the output of svn status.
+ *
+ * @param stdout Output of svn status.
+ * @return Changed paths with their status, in output order.
+ */
+export function parseStatus(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.replace(/\r$/, ''))
+        .map((line) => ({
+        status: getStatusType(line.slice(0, 2)),
+        path: line.slice(8).split('\\').join('/'),
+    }))
+        .filter((entry) => null !== entry.status && '' !== entry.path);
+}
+const STATUS_TYPES = {
+    A: 'added',
+    M: 'modified',
+    D: 'deleted',
+    R: 'replaced',
+    '!': 'missing',
+    '?': 'unversioned',
+    I: 'unversioned',
+    C: 'conflicted',
+    '~': 'obstructed',
+};
+/**
+ * Map the item and property columns of a status line to a status type.
+ *
+ * @param columns First two characters of the status line.
+ * @return Status type, or null for unchanged paths and other lines.
+ */
+function getStatusType(columns) {
+    const [item = ' ', property = ' '] = columns;
+    if (Object.hasOwn(STATUS_TYPES, item)) {
+        return STATUS_TYPES[item] ?? null;
+    }
+    if (' ' === item && 'M' === property) {
+        return 'modified';
+    }
+    if (' ' === item && 'C' === property) {
+        return 'conflicted';
+    }
+    return null;
+}
+/**
+ * Minimal Subversion client around the svn command line.
+ *
+ * Every command runs non-interactively without caching credentials. The
+ * password is only sent with commits, on the standard input, so it never
+ * appears in the process list or the logs.
+ */
+export class Svn {
+    runner;
+    username;
+    password;
+    logger;
+    /**
+     * @param options Runner, credentials and logger.
+     */
+    constructor(options = {}) {
+        this.runner = options.runner ?? createSvnRunner();
+        this.username = options.username ?? null;
+        this.password = options.password ?? null;
+        this.logger = options.logger ?? null;
+    }
+    /**
+     * Run an svn subcommand with the global options.
+     *
+     * @param input Arguments, working directory and standard input.
+     * @return Command output.
+     */
+    async run(input) {
+        const [subcommand = '', ...rest] = input.args;
+        const args = [
+            subcommand,
+            '--non-interactive',
+            '--no-auth-cache',
+            ...rest,
+        ];
+        this.logger?.debug(`svn ${args.join(' ')}`);
+        return this.runner({ ...input, args });
+    }
+    /**
+     * Check out a repository, by default with only its top-level directories
+     * so that update() can add the ones that are needed.
+     *
+     * @param input URL, working copy path and depth.
+     */
+    async checkout(input) {
+        const { url, path, depth = 'immediates' } = input;
+        await this.run({
+            args: [
+                'checkout',
+                '--depth',
+                depth,
+                '--',
+                url,
+                toSvnPath(path),
+            ],
+        });
+    }
+    /**
+     * Update a path of a sparse working copy to a new depth.
+     *
+     * @param input Working copy path and depth.
+     */
+    async update(input) {
+        await this.run({
+            args: [
+                'update',
+                '--set-depth',
+                input.depth,
+                '--',
+                toSvnPath(input.path),
+            ],
+        });
+    }
+    /**
+     * List the entries of a repository directory.
+     *
+     * @param url Repository or working copy path.
+     * @return Entry names, directories with a trailing slash.
+     */
+    async list(url) {
+        const { stdout } = await this.run({ args: ['list', '--', url] });
+        return stdout.split('\n').filter(Boolean);
+    }
+    /**
+     * Get the changed, unversioned and missing paths of a working copy,
+     * including the files that svn ignores by default.
+     *
+     * @param path Working copy path.
+     * @return Changed paths relative to the working copy.
+     */
+    async status(path) {
+        const { stdout } = await this.run({
+            args: ['status', '--no-ignore', '--ignore-externals'],
+            cwd: path,
+        });
+        return parseStatus(stdout);
+    }
+    /**
+     * Schedule unversioned paths for addition, including the files that svn
+     * ignores by default and missing parent directories.
+     *
+     * @param input Paths and working directory.
+     */
+    async add(input) {
+        await this.runForPaths(['add', '--no-ignore', '--parents'], input);
+    }
+    /**
+     * Schedule paths for deletion, also when they're already missing.
+     *
+     * @param input Paths and working directory.
+     */
+    async remove(input) {
+        await this.runForPaths(['delete', '--force'], input);
+    }
+    /**
+     * Copy a path with its history.
+     *
+     * @param input Source, target and working directory.
+     */
+    async copy(input) {
+        await this.run({
+            args: [
+                'copy',
+                '--',
+                toSvnPath(input.from),
+                toSvnPath(input.to),
+            ],
+            cwd: input.cwd,
+        });
+    }
+    /**
+     * Set a property on paths.
+     *
+     * @param input Property name and value, paths and working directory.
+     */
+    async propset(input) {
+        await this.runForPaths(['propset', input.name, input.value], input);
+    }
+    /**
+     * Commit a working copy with the credentials.
+     *
+     * @param input Working copy path and message.
+     * @return Committed revision, or null when there was nothing to commit.
+     */
+    async commit(input) {
+        const auth = this.username ? ['--username', this.username] : [];
+        const password = this.password ? ['--password-from-stdin'] : [];
+        const { stdout } = await this.run({
+            args: [
+                'commit',
+                '--message',
+                input.message,
+                ...auth,
+                ...password,
+            ],
+            cwd: input.path,
+            input: this.password ? `${this.password}\n` : undefined,
+        });
+        const revision = /Committed revision (\d+)\./.exec(stdout)?.[1];
+        return revision ? Number(revision) : null;
+    }
+    /**
+     * Run a subcommand for paths, in batches so that the argument list stays
+     * below the operating system limit.
+     *
+     * @param args  Subcommand and options.
+     * @param input Paths and working directory.
+     */
+    async runForPaths(args, input) {
+        const batchSize = 500;
+        for (let start = 0; start < input.paths.length; start += batchSize) {
+            await this.run({
+                args: [
+                    ...args,
+                    '--',
+                    ...input.paths
+                        .slice(start, start + batchSize)
+                        .map(toSvnPath),
+                ],
+                cwd: input.cwd,
+            });
+        }
+    }
+}

package/dist/sync.d.ts

@@ -0,0 +1,32 @@
+export interface SyncDirectoryInput {
+    /** Directory with the files to copy. */
+    sourceDir: string;
+    /** Relative file paths to copy, from selectFiles(). */
+    files: string[];
+    /** Directory to make identical to the selected files. */
+    targetDir: string;
+}
+export interface SyncResult {
+    /** Files that were new or changed and got copied. */
+    copied: string[];
+    /** Files that were deleted because they're no longer selected. */
+    deleted: string[];
+}
+/**
+ * Copy a file unless the target already has the same contents.
+ *
+ * @param source Source file path.
+ * @param target Target file path.
+ * @return Whether the file was copied.
+ */
+export declare function copyFileIfChanged(source: string, target: string): Promise<boolean>;
+/**
+ * Make a directory contain exactly the selected files, like rsync with
+ * --delete: delete files that aren't selected and the directories they
+ * leave empty, then copy the files that are new or changed. Files that
+ * didn't change are left alone, so that svn sees only real changes.
+ *
+ * @param input Source directory, selected files and target directory.
+ * @return Copied and deleted files, relative to the target directory.
+ */
+export declare function syncDirectory(input: SyncDirectoryInput): Promise<SyncResult>;

package/dist/sync.js

@@ -0,0 +1,90 @@
+import { copyFile, mkdir, readdir, readFile, rm, rmdir, stat, } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import ignore from 'ignore';
+import { isErrorCode, selectFiles } from "./file-selection.js";
+/**
+ * SVN metadata directory, which a sync never copies, deletes or lists.
+ */
+const SVN_DIRECTORY = '.svn';
+/**
+ * Check if two files have the same contents.
+ *
+ * @param source Source file path.
+ * @param target Target file path.
+ * @return Whether the target exists with the same contents.
+ */
+async function isSameFile(source, target) {
+    const targetStats = await stat(target).catch((error) => {
+        if (isErrorCode(error, 'ENOENT')) {
+            return null;
+        }
+        throw error;
+    });
+    const sourceStats = await stat(source);
+    if (!targetStats?.isFile() || targetStats.size !== sourceStats.size) {
+        return false;
+    }
+    const [sourceContents, targetContents] = await Promise.all([
+        readFile(source),
+        readFile(target),
+    ]);
+    return sourceContents.equals(targetContents);
+}
+/**
+ * Copy a file unless the target already has the same contents.
+ *
+ * @param source Source file path.
+ * @param target Target file path.
+ * @return Whether the file was copied.
+ */
+export async function copyFileIfChanged(source, target) {
+    if (await isSameFile(source, target)) {
+        return false;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+    return true;
+}
+/**
+ * Remove the empty directories below a directory, deepest first.
+ *
+ * @param dir  Directory to clean up.
+ * @param root Whether this is the top directory, which is kept.
+ */
+async function removeEmptyDirectories(dir, root = true) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const subdirs = entries.filter((entry) => entry.isDirectory() && SVN_DIRECTORY !== entry.name);
+    for (const subdir of subdirs) {
+        await removeEmptyDirectories(join(dir, subdir.name), false);
+    }
+    if (!root && 0 === (await readdir(dir)).length) {
+        await rmdir(dir);
+    }
+}
+/**
+ * Make a directory contain exactly the selected files, like rsync with
+ * --delete: delete files that aren't selected and the directories they
+ * leave empty, then copy the files that are new or changed. Files that
+ * didn't change are left alone, so that svn sees only real changes.
+ *
+ * @param input Source directory, selected files and target directory.
+ * @return Copied and deleted files, relative to the target directory.
+ */
+export async function syncDirectory(input) {
+    const { sourceDir, files, targetDir } = input;
+    const selected = new Set(files);
+    await mkdir(targetDir, { recursive: true });
+    const existing = await selectFiles(targetDir, ignore().add(`${SVN_DIRECTORY}/`));
+    const deleted = existing.filter((file) => !selected.has(file));
+    for (const file of deleted) {
+        await rm(join(targetDir, file));
+    }
+    await removeEmptyDirectories(targetDir);
+    const copied = [];
+    for (const file of files) {
+        if (await copyFileIfChanged(join(sourceDir, file), join(targetDir, file))) {
+            copied.push(file);
+        }
+    }
+    return { copied, deleted };
+}

package/dist/unzip.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Archive entry type, from the Unix mode in the entry attributes.
+ */
+export type ZipEntryType = 'file' | 'directory' | 'symlink';
+export interface ZipEntryInfo {
+    /** Entry path inside the archive. */
+    path: string;
+    /** Entry type. */
+    type: ZipEntryType;
+}
+export interface ExtractZipInput {
+    /** Archive path. */
+    zipPath: string;
+    /** Directory to extract into. */
+    targetDir: string;
+    /** Root folder that every entry must be in, stripped when extracting. */
+    rootFolder?: string | null;
+}
+/**
+ * List the entries of an archive without extracting it.
+ *
+ * @param zipPath Archive path.
+ * @return Entries in archive order.
+ */
+export declare function readZipEntries(zipPath: string): Promise<ZipEntryInfo[]>;
+/**
+ * Collect the problems that make an archive unsafe or unexpected to extract:
+ * absolute paths, ".." segments, backslashes, symbolic links and entries
+ * outside the root folder.
+ *
+ * @param entries    Entries from readZipEntries().
+ * @param rootFolder Root folder that every entry must be in, or null.
+ * @return Error messages, empty when the archive can be extracted.
+ */
+export declare function getZipEntryErrors(entries: ZipEntryInfo[], rootFolder?: string | null): string[];
+/**
+ * Extract an archive after checking every entry with getZipEntryErrors(),
+ * so that nothing is written outside the target directory. The root folder,
+ * when set, is stripped from the paths.
+ *
+ * @param  input Archive, target directory and root folder.
+ * @return Extracted file paths relative to the target directory, sorted.
+ * @throws {ValidationError} If the archive has unsafe or unexpected entries.
+ */
+export declare function extractZip(input: ExtractZipInput): Promise<string[]>;