publish_packages.js

#!/usr/bin/env node

/**
* @license Apache-2.0
*
* Copyright (c) 2021 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*    http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

/* eslint-disable node/no-sync, no-console, max-statements, max-lines-per-function, max-lines, node/no-unsupported-features/node-builtins */

'use strict';

// MODULES //

var join = require( 'path' ).join;
var shell = require( 'child_process' ).execSync;
var fs = require( 'fs' );
var tmpdir = require( 'os' ).tmpdir;
var logger = require( 'debug' );
var ghpages = require( 'gh-pages' );
var semver = require( 'semver' );
var CLI = require( '@stdlib/cli/ctor' );
var setTopics = require( '@stdlib/_tools/github/set-topics' );
var createRepo = require( '@stdlib/_tools/github/create-repo' );
var name2bucket = require( '@stdlib/_tools/pkgs/name2bucket' );
var writeFileSync = require( '@stdlib/fs/write-file' ).sync;
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
var readJSON = require( '@stdlib/fs/read-json' ).sync;
var existsSync = require( '@stdlib/fs/exists' ).sync;
var hasOwnProp = require( '@stdlib/assert/has-own-property' );
var contains = require( '@stdlib/assert/contains' );
var memoize = require( '@stdlib/utils/memoize' );
var repeat = require( '@stdlib/string/repeat' );
var trim = require( '@stdlib/string/trim' );
var copy = require( '@stdlib/utils/copy' );
var sample = require( '@stdlib/random/sample' );
var rootDir = require( '@stdlib/_tools/utils/root-dir' );
var rescape = require( '@stdlib/utils/escape-regexp-string' );
var replace = require( '@stdlib/string/replace' );
var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
var removeFirst = require( '@stdlib/string/remove-first' );
var reFromString = require( '@stdlib/utils/regexp-from-string' );
var startsWith = require( '@stdlib/string/starts-with' );
var substringAfterLast = require( '@stdlib/string/substring-after-last' );
var currentYear = require( '@stdlib/time/current-year' );
var namespaceDeps = require( '@stdlib/_tools/pkgs/namespace-deps' );
var depList = require( '@stdlib/_tools/pkgs/dep-list' );
var name2standalone = require( '@stdlib/_tools/pkgs/name2standalone' );
var generateChangelog = require( '@stdlib/_tools/changelog/generate' );
var toposort = require( '@stdlib/_tools/pkgs/toposort' ).sync;
var ENV = require( '@stdlib/process/env' );


// VARIABLES //

var cli = new CLI();
var flags = cli.flags();
var args = cli.args();

var debug = logger( 'scripts:publish-packages' );

var START_PKG_INDEX = parseInt( flags[ 'start-index' ], 10 ) || 0;
var END_PKG_INDEX = ( flags[ 'end-index' ] === void 0 ) ? 9999 : parseInt( flags[ 'end-index' ], 10 );
var MAX_TREE_DEPTH = 99;
var KEEP_ALIVE_SAMPLE_SIZE = 1000;

var topics = setTopics.factory({
	'token': ENV.GITHUB_TOKEN
}, onTopics );

var CURRENT_YEAR = currentYear();

var INSTALLATION_SECTION_BASIC = [
	'<section class="installation">',
	'',
	'## Installation',
	'',
	'```bash',
	'npm install @stdlib/<pkg>',
	'```',
	'',
	'</section>',
	''
].join( '\n' );
var INSTALLATION_SECTION_BUNDLES = [
	'<section class="installation">',
	'',
	'## Installation',
	'',
	'```bash',
	'npm install @stdlib/<pkg>',
	'```',
	'',
	'Alternatively,',
	'',
	'-   To load the package in a website via a `script` tag without installation and bundlers, use the [ES Module][es-module] available on the [`esm`][esm-url] branch (see [README][esm-readme]).',
	'-   If you are using Deno, visit the [`deno`][deno-url] branch (see [README][deno-readme] for usage intructions).',
	'-   For use in Observable, or in browser/node environments, use the [Universal Module Definition (UMD)][umd] build available on the [`umd`][umd-url] branch (see [README][umd-readme]).',
	'<cli>',
	'The [branches.md][branches-url] file summarizes the available branches and displays a diagram illustrating their relationships.',
	'',
	'To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.',
	'',
	'</section>',
	''
].join( '\n' );
var INSTALLATION_SECTION_BUNDLES_CLI = [
	'-   To use as a general utility for the command line, install the corresponding [CLI package][cli-section] globally.',
	''
].join( '\n' );
var CLI_INSTALLATION_SECTION = [
	'<section class="installation">',
	'',
	'## Installation',
	'',
	'To use as a general utility, install the CLI package globally',
	'',
	'```bash',
	'npm install -g @stdlib/<pkg>-cli',
	'```',
	'',
	'</section>',
	''
].join( '\n' );

var mainDir = join( __dirname, '..', '..', '..', '..', '..' );
var DOTFILES = [ '.editorconfig', '.gitignore', '.gitattributes', '.npmrc', 'CONTRIBUTORS', 'NOTICE', 'CITATION.cff' ];

var WORKFLOW_CLOSE_PULLS = [
	'#/',
	'# @license Apache-2.0',
	'#',
	'# Copyright (c) 2021 The Stdlib Authors.',
	'#',
	'# Licensed under the Apache License, Version 2.0 (the "License");',
	'# you may not use this file except in compliance with the License.',
	'# You may obtain a copy of the License at',
	'#',
	'#    http://www.apache.org/licenses/LICENSE-2.0',
	'#',
	'# Unless required by applicable law or agreed to in writing, software',
	'# distributed under the License is distributed on an "AS IS" BASIS,',
	'# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
	'# See the License for the specific language governing permissions and',
	'# limitations under the License.',
	'#/',
	'',
	'# Workflow name:',
	'name: close_pull_requests',
	'',
	'# Workflow triggers:',
	'on:',
	'  pull_request_target:',
	'    types: [opened]',
	'',
	'# Workflow jobs:',
	'jobs:',
	'',
	'  # Define job to close all pull requests:',
	'  run:',
	'',
	'    # Define the type of virtual host machine on which to run the job:',
	'    runs-on: ubuntu-latest',
	'',
	'    # Define the sequence of job steps...',
	'    steps:',
	'',
	'      # Close pull request',
	'      - name: \'Close pull request\'',
	'        # Pin action to full length commit SHA corresponding to v3.1.2',
	'        uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448',
	'        with:',
	'          comment: |',
	'            Thank you for submitting a pull request. :raised_hands:',
	'            ',
	'            We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib).',
	'            ',
	'            We kindly request that you submit this pull request against the [respective directory](<pkg-path>) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions.',
	'            ',
	'            Thank you again, and we look forward to receiving your contribution! :smiley:',
	'            ',
	'            Best,',
	'            The stdlib team'
].join( '\n' );
var PULL_REQUEST_TEMPLATE = [
	'<!-- ----------^ Click "Preview"! -->',
	'',
	'We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](<pkg-path>) of the main repository where we’ll review and provide feedback. ',
	'',
	'If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib.',
	'',
	'We look forward to receiving your contribution! :smiley:'
].join( '\n' );
var FUNDING = {
	'type': 'opencollective',
	'url': 'https://opencollective.com/stdlib'
};
var BRANCHES = [
	'<!--',
	'',
	'@license Apache-2.0',
	'',
	'Copyright (c) 2022 The Stdlib Authors.',
	'',
	'Licensed under the Apache License, Version 2.0 (the "License");',
	'you may not use this file except in compliance with the License.',
	'You may obtain a copy of the License at',
	'',
	'    http://www.apache.org/licenses/LICENSE-2.0',
	'',
	'Unless required by applicable law or agreed to in writing, software',
	'distributed under the License is distributed on an "AS IS" BASIS,',
	'WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
	'See the License for the specific language governing permissions and',
	'limitations under the License.',
	'',
	'-->',
	'',
	'# Branches',
	'',
	'This repository has the following branches:',
	'',
	'-   **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place.',
	'-   **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network).',
	'-   **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]).',
	'-   **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]).',
	'-   **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]).',
	'',
	'The following diagram illustrates the relationships among the above branches:',
	'',
	'```mermaid',
	'graph TD;',
	'A[stdlib]-->|generate standalone package|B;',
	'B[main] -->|productionize| C[production];',
	'C -->|bundle| D[esm];',
	'C -->|bundle| E[deno];',
	'C -->|bundle| F[umd];',
	'',
	'%% click A href "<pkg-path>"',
	'%% click B href "https://github.com/stdlib-js/<pkg>/tree/main"',
	'%% click C href "https://github.com/stdlib-js/<pkg>/tree/production"',
	'%% click D href "https://github.com/stdlib-js/<pkg>/tree/esm"',
	'%% click E href "https://github.com/stdlib-js/<pkg>/tree/deno"',
	'%% click F href "https://github.com/stdlib-js/<pkg>/tree/umd"',
	'```',
	'',
	'[stdlib-url]: <pkg-path>',
	'[production-url]: https://github.com/stdlib-js/<pkg>/tree/production',
	'[deno-url]: https://github.com/stdlib-js/<pkg>/tree/deno',
	'[deno-readme]: https://github.com/stdlib-js/<pkg>/blob/deno/README.md',
	'[umd-url]: https://github.com/stdlib-js/<pkg>/tree/umd',
	'[umd-readme]: https://github.com/stdlib-js/<pkg>/blob/umd/README.md',
	'[esm-url]: https://github.com/stdlib-js/<pkg>/tree/esm',
	'[esm-readme]: https://github.com/stdlib-js/<pkg>/blob/esm/README.md'
].join( '\n' );
var BRANCHES_WITH_CLI = [
	'<!--',
	'',
	'@license Apache-2.0',
	'',
	'Copyright (c) 2023 The Stdlib Authors.',
	'',
	'Licensed under the Apache License, Version 2.0 (the "License");',
	'you may not use this file except in compliance with the License.',
	'You may obtain a copy of the License at',
	'',
	'    http://www.apache.org/licenses/LICENSE-2.0',
	'',
	'Unless required by applicable law or agreed to in writing, software',
	'distributed under the License is distributed on an "AS IS" BASIS,',
	'WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
	'See the License for the specific language governing permissions and',
	'limitations under the License.',
	'',
	'-->',
	'',
	'# Branches',
	'',
	'This repository has the following branches:',
	'',
	'-   **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place.',
	'-   **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network).',
	'-   **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]).',
	'-   **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]).',
	'-   **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]).',
	'-   **cli**: [CLI][cli-url] branch for use on the command line.',
	'',
	'The following diagram illustrates the relationships among the above branches:',
	'',
	'```mermaid',
	'graph TD;',
	'A[stdlib]-->|generate standalone package|B;',
	'B[main] -->|productionize| C[production];',
	'C -->|bundle| D[esm];',
	'C -->|bundle| E[deno];',
	'C -->|bundle| F[umd];',
	'C -->|extract| G[cli];',
	'',
	'%% click A href "<pkg-path>"',
	'%% click B href "https://github.com/stdlib-js/<pkg>/tree/main"',
	'%% click C href "https://github.com/stdlib-js/<pkg>/tree/production"',
	'%% click D href "https://github.com/stdlib-js/<pkg>/tree/esm"',
	'%% click E href "https://github.com/stdlib-js/<pkg>/tree/deno"',
	'%% click F href "https://github.com/stdlib-js/<pkg>/tree/umd"',
	'%% click G href "https://github.com/stdlib-js/<pkg>/tree/cli"',
	'```',
	'',
	'[stdlib-url]: <pkg-path>',
	'[production-url]: https://github.com/stdlib-js/<pkg>/tree/production',
	'[deno-url]: https://github.com/stdlib-js/<pkg>/tree/deno',
	'[deno-readme]: https://github.com/stdlib-js/<pkg>/blob/deno/README.md',
	'[umd-url]: https://github.com/stdlib-js/<pkg>/tree/umd',
	'[umd-readme]: https://github.com/stdlib-js/<pkg>/blob/umd/README.md',
	'[esm-url]: https://github.com/stdlib-js/<pkg>/tree/esm',
	'[esm-readme]: https://github.com/stdlib-js/<pkg>/blob/esm/README.md',
	'[cli-url]: https://github.com/stdlib-js/<pkg>/tree/cli'
].join( '\n' );

var RE_CLI_USAGE_SECTION = /(## CLI\r?\n\r?\n\s*)(<!-- CLI usage documentation\. -->\r?\n\r?\n\s*)?<section\s+class\s*=\s*"usage"\s*>/;
var RE_C_USAGE_SECTION = /(<!-- C usage documentation\. -->\r?\n\r?\n\s*)<section\s+class\s*=\s*"usage"\s*>/;
var RE_USAGE_SECTION = /<section\s+class\s*=\s*"usage"\s*>/;
var BASIC_GITHUB_TOPICS = [
	'nodejs',
	'javascript',
	'stdlib',
	'node',
	'node-js'
];
var RE_ALLOWED_TOPIC_CHARS = /^[A-Z0-9-]+$/i;
var memoizedNPMversionForDeps = memoize( npmVersion );
var memoizedNPMversionForDevDeps = memoize( npmVersion );


// FUNCTIONS //

/**
* Returns a cron schedule for a given package.
*
* @private
* @param {string} pkg - package name
* @returns {string} cron schedule
*/
function cronSchedule( pkg ) {
	var mins = name2bucket( pkg, 60 );
	var hrs = name2bucket( pkg, 24 );
	var dow = name2bucket( pkg, 7 );
	return mins+' '+hrs+' * * '+dow;
}

/**
* Gets the latest version of a package on npm.
*
* @private
* @param {string} pkg - package name
* @returns {string} latest version published to npm
*/
function npmVersion( pkg ) {
	var command = 'npm view '+pkg+' version --silent';
	try {
		return '^'+trim( shell( command ).toString() );
	} catch ( error ) {
		debug( 'Encountered an error when attempting to get the latest version of package `%s`: %s', pkg, error.message );
		return 'github:stdlib-js/' + replace( pkg, '@stdlib/', '' ) + '#main';
	}
}

/**
* Populates the dependencies and devDependencies fields of a package.json object.
*
* @private
* @param {Object} pkgJSON - package.json object
* @param {Array} deps - dependencies
* @param {Array} devDeps - devDependencies
* @param {Object} mainJSON - main repo package.json object
* @param {boolean} useGitHub - boolean indicating whether to use GitHub URLs for dependencies
* @returns {Object} package.json object
*/
function populateDeps( pkgJSON, deps, devDeps, mainJSON, useGitHub ) {
	var mainVersion;
	var out;
	var dep;
	var i;

	out = copy( pkgJSON );
	for ( i = 0; i < deps.length; i++ ) {
		dep = deps[ i ];
		if ( startsWith( dep, '@stdlib' ) ) {
			if (
				!contains( dep, '_tools' ) &&
				( !contains( dep, 'plot' ) || dep === '@stdlib/plot' )
			) {
				if ( useGitHub ) {
					out.dependencies[ dep ] = 'github:stdlib-js/' + replace( dep, '@stdlib/', '' ) + '#main';
				} else {
					out.dependencies[ dep ] = memoizedNPMversionForDeps( dep );
				}
			}
		} else {
			out.dependencies[ dep ] = mainJSON.dependencies[ dep ];
		}
	}
	for ( i = 0; i < devDeps.length; i++ ) {
		dep = devDeps[ i ];
		if (
			!contains( deps, dep )
		) {
			if (
				startsWith( dep, '@stdlib' )
			) {
				if (
					!contains( dep, '_tools' ) &&
					( !contains( dep, 'plot' ) || dep === '@stdlib/plot' )
				) {
					if ( useGitHub ) {
						out.devDependencies[ dep ] = 'github:stdlib-js/' + replace( dep, '@stdlib/', '' ) + '#main';
					} else {
						out.devDependencies[ dep ] = memoizedNPMversionForDevDeps( dep );
					}
				}
			} else {
				mainVersion = mainJSON.devDependencies[ dep ];
				out.devDependencies[ dep ] = mainVersion;
			}
		}
	}
	return out;
}

/**
* Cleans up the `gh-pages` cache directory.
*
* @private
* @returns {void}
*/
function cleanCache() {
	var command = 'rm -rf '+join( mainDir, 'node_modules', '.cache', 'gh-pages' );
	console.log( 'Clean-up cached gh-pages files: %s', command );
	console.log( shell( command ).toString() );
}

/**
* Returns a section for the main project to be appended to the standalone package README.md files.
*
* @private
* @param {boolean} customLicense - boolean indicating whether the standalone package contains a custom license file
* @param {string} branch - branch for build status badge
* @param {boolean} hasBundles - boolean indicating whether the standalone package contains browser bundles
* @param {boolean} hasCLI - boolean indicating whether the standalone package contains a CLI
* @returns {string} main repo section
*/
function mainRepoSection( customLicense, branch, hasBundles, hasCLI ) {
	/* eslint-disable function-call-argument-newline, function-paren-newline */
	var out = [
		'',
		'<section class="main-repo" >',
		'',
		'* * *',
		'',
		'## Notice',
		'',
		'This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.',
		'',
		'For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib].',
		'',
		'#### Community',
		'',
		'[![Chat][chat-image]][chat-url]',
		'',
		'---'
	];
	if ( !customLicense ) {
		out.push(
			'',
			'## License',
			'',
			'See [LICENSE][stdlib-license].',
			''
		);
	}
	out.push(
		'',
		'## Copyright',
		'',
		'Copyright &copy; 2016-'+CURRENT_YEAR+'. The Stdlib [Authors][stdlib-authors].',
		'',
		'</section>',
		'',
		'<!-- /.stdlib -->',
		'',
		'<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->',
		'',
		'<section class="links">',
		'',
		'[npm-image]: http://img.shields.io/npm/v/@stdlib/<pkg>.svg',
		'[npm-url]: https://npmjs.org/package/@stdlib/<pkg>',
		'',
		'[test-image]: https://github.com/stdlib-js/<pkg>/actions/workflows/test.yml/badge.svg?branch=' + branch,
		'[test-url]: https://github.com/stdlib-js/<pkg>/actions/workflows/test.yml?query=branch:' + branch,
		'',
		'[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/<pkg>/main.svg',
		'[coverage-url]: https://codecov.io/github/stdlib-js/<pkg>?branch=main',
		'',
		'<!--',
		'',
		'[dependencies-image]: https://img.shields.io/david/stdlib-js/<pkg>.svg',
		'[dependencies-url]: https://david-dm.org/stdlib-js/<pkg>/main',
		'',
		'-->',
		'',
		'[chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg',
		'[chat-url]: https://app.gitter.im/#/room/#stdlib-js_stdlib:gitter.im',
		'',
		'[stdlib]: https://github.com/stdlib-js/stdlib',
		'',
		'[stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors'
	);
	if ( hasCLI ) {
		out.push(
			'',
			'[cli-section]: https://github.com/stdlib-js/<pkg>#cli',
			'[cli-url]: https://github.com/stdlib-js/<pkg>/tree/cli',
			'[@stdlib/<pkg>]: https://github.com/stdlib-js/<pkg>'
		);
	}
	if ( hasBundles ) {
		out.push(
			'',
			'[umd]: https://github.com/umdjs/umd',
			'[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules',
			'',
			'[deno-url]: https://github.com/stdlib-js/<pkg>/tree/deno',
			'[deno-readme]: https://github.com/stdlib-js/<pkg>/blob/deno/README.md',
			'[umd-url]: https://github.com/stdlib-js/<pkg>/tree/umd',
			'[umd-readme]: https://github.com/stdlib-js/<pkg>/blob/umd/README.md',
			'[esm-url]: https://github.com/stdlib-js/<pkg>/tree/esm',
			'[esm-readme]: https://github.com/stdlib-js/<pkg>/blob/esm/README.md',
			'[branches-url]: https://github.com/stdlib-js/<pkg>/blob/main/branches.md'
		);
	}
	if ( !customLicense ) {
		out.push(
			'',
			'[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/<pkg>/main/LICENSE'
		);
	}
	return out.join( '\n' );

	/* eslint-enable function-call-argument-newline, function-paren-newline */
}

/**
* Creates a list of GitHub topics.
*
* @private
* @param {StringArray} words - list of keywords
* @returns {StringArray} list of topics
*/
function createTopics( words ) {
	var word;
	var out;
	var i;

	out = [];
	for ( i = 0; i < words.length; i++ ) {
		word = words[ i ];
		if (
			!startsWith( word, 'std' ) &&
			word.length <= 35 // GitHub topics may not have more than 35 characters
		) {
			word = replace( word, ' ', '-' ); // GitHub topics may not include spaces, but allow hyphens
			if ( RE_ALLOWED_TOPIC_CHARS.test( word ) ) {
				out.push( word );
			}
		}
	}
	return BASIC_GITHUB_TOPICS.concat( out ).slice( 0, 20 ); // GitHub repositories may not have more than 20 topics
}

/**
* Function invoked upon replacing the topics of a repository.
*
* @private
* @param {(Error|null)} error - encountered error
* @param {Object} data - response data
* @param {Object} info - response info
* @returns {void}
*/
function onTopics( error, data, info ) {
	if ( error ) {
		return console.error( error );
	}
	console.log( 'Replaced topics for repository.' );
	console.log( 'Response data: '+JSON.stringify( data ) );
	console.log( 'Rate limit: '+JSON.stringify( info ) );
}

/**
* Publishes a package to the respective GitHub repository.
*
* @private
* @param {string} pkg - package name
* @param {Function} clbk - callback function
* @throws {Error} no input files
* @returns {void}
*/
function publish( pkg, clbk ) {
	var fmtProdMsgVersion;
	var triggerRelease;
	var customLicense;
	var isTopLevelNS;
	var workflowPath;
	var ghpagesOpts;
	var jscodeshift;
	var pkgJsonPath;
	var releaseType;
	var extractCLI;
	var repoExists;
	var readmePath;
	var noBundles;
	var changelog;
	var contents;
	var mainJSON;
	var schedule;
	var workflow;
	var command;
	var devDeps;
	var distPkg;
	var pkgJSON;
	var version;
	var badges;
	var branch;
	var nLines;
	var readme;
	var mdPath;
	var about;
	var alias;
	var deps;
	var dist;
	var file;
	var opts;
	var src;
	var pth;
	var i;

	src = join( mainDir, 'lib/node_modules', '@stdlib', pkg );
	distPkg = replace( pkg, /\//g, '-' );
	pth = 'https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/'+pkg;

	dist = join( mainDir, 'build', '@stdlib', distPkg );
	command = 'git ls-remote https://'+ ENV.GITHUB_TOKEN + '@github.com/stdlib-js/'+distPkg+'.git main';
	try {
		shell( command );
		repoExists = true;
	} catch ( error ) {
		console.error( 'Encountered an error when attempting to check whether the repository exists. Error: %s', error.message );
		repoExists = false;
	}
	command = 'git ls-remote --tags --sort="v:refname" https://'+ ENV.GITHUB_TOKEN + '@github.com/stdlib-js/'+distPkg+'.git | grep -E \'v[0-9]+.[0-9]+.[0-9]+\'';
	debug( 'Executing command to retrieve last version: %s', command );
	try {
		command = shell( command ).toString();
		version = substringAfterLast( command, '/' );
		version = replace( version, /[-a-z.]*\^{}/, '' );
		version = trim( removeFirst( version ) ); // Remove leading `v`...
	} catch ( error ) {
		console.error( 'Encountered an error when attempting to retrieve the last version. Error: %s', error.message );
	}
	if ( !version ) {
		version = '0.0.0';
	}
	else if ( flags[ 'only-unpublished' ] ) {
		// Case: the package has already been published (as indicated by the presence of a version tag) and the `--only-unpublished` flag is set, so we skip the package...
		return invokeCallback( null, 'skipped' );
	}

	if ( flags[ 'release-type' ] ) {
		// Case: release type specified, so we generate a changelog for the specified release type...
		changelog = generateChangelog( '@stdlib/'+pkg, {
			'releaseType': flags[ 'release-type' ]
		});
	} else {
		// Case: no release type specified, so we generate a changelog for a non-release...
		changelog = generateChangelog( '@stdlib/'+pkg );
	}
	releaseType = changelog.releaseType;

	mainJSON = readJSON( join( mainDir, 'package.json' ) );

	console.log( 'Creating directory and copying source files...' );
	command = 'mkdir -p '+dist;
	debug( 'Creating build directory: %s', command );
	shell( command );

	isTopLevelNS = !contains( pkg, '/' );
	if ( isTopLevelNS ) {
		// Copy all files and subdirectories:
		command = 'cp -r '+src+'/* '+dist;
	}
	else {
		// Do not copy nested packages which will instead be pulled in as separate dependencies:
		command = 'rsync -r --ignore-missing-args --include=\'benchmark/***\' --include=\'bin/***\' --include=\'data/***\' --include=\'docs/***\' --include=\'etc/***\' --include=\'examples/***\' --include=\'lib/***\' --include=\'include/***\' --include=\'scripts/***\' --include=\'src/***\' --include=\'static/***\'  --include=\'test/***\' --exclude=\'*/***\' '+src+'/*** '+dist;
	}
	debug( 'Copying files: %s', command );
	shell( command );

	debug( 'Copying configuration files...' );
	for ( i = 0; i < DOTFILES.length; i++ ) {
		file = DOTFILES[ i ];
		fs.copyFileSync( join( mainDir, file ), join( dist, file ) );
	}
	if ( existsSync( join( dist, 'LICENSE' ) ) ) {
		customLicense = true;
	} else {
		fs.copyFileSync( join( __dirname, 'templates', 'license_apache2.txt' ), join( dist, 'LICENSE' ) );
		command = [
			'# Extract custom licenses from all descendant packages:',
			'find '+src+' -type f -name "LICENSE" -exec cat {} \\; > LICENSE.tmp',
			'',
			'# Check whether LICENSE.tmp is empty:',
			'if [ -s LICENSE.tmp ]; then',
			'',
			'  # Attach attribution notice to LICENSE file:',
			'  cat '+dist+'/LICENSE '+join( __dirname, 'templates', 'license_attribution.txt' )+' LICENSE.tmp > LICENSE.out',
			'',
			'  # Remove duplicate licenses, i.e., multiline strings:',
			'  awk -v RS= \'!x[$0]++{print; print ""}\' LICENSE.out > LICENSE.tmp',
			'',
			'  # Move LICENSE.tmp to LICENSE:',
			'  mv LICENSE.tmp '+dist+'/LICENSE',
			'',
			'  # Remove temporary file:',
			'  rm LICENSE.out',
			'fi'
		].join( '\n' );
		shell( command );

		customLicense = false;
	}
	fs.copyFileSync( join( __dirname, 'templates', '.npmignore.txt' ), join( dist, '.npmignore' ) );
	fs.copyFileSync( join( __dirname, 'templates', 'Makefile.txt' ), join( dist, 'Makefile' ) );
	fs.copyFileSync( join( __dirname, 'templates', '.eslintrc.js.txt' ), join( dist, '.eslintrc.js' ) );
	writeFileSync( join( dist, 'CHANGELOG.md' ), changelog.content );
	fs.copyFileSync( join( __dirname, 'templates', 'SECURITY.md.txt' ), join( dist, 'SECURITY.md' ) );

	pkgJsonPath = join( dist, 'package.json' );
	pkgJSON = readJSON( pkgJsonPath );
	pkgJSON.name = '@stdlib/'+distPkg;

	// Check if the package should not contain browser bundles:
	noBundles = pkgJSON[ '__stdlib__' ] &&
	pkgJSON[ '__stdlib__' ][ 'envs' ] &&
	( pkgJSON[ '__stdlib__' ][ 'envs' ][ 'browser' ] === false );

	if ( isTopLevelNS ) {
		deps = namespaceDeps( '@stdlib/'+pkg, {
			'level': 1,
			'dev': false
		});
		deps = name2standalone( deps );
		devDeps = namespaceDeps( '@stdlib/'+pkg, {
			'level': 1,
			'dev': true
		});
		devDeps = name2standalone( devDeps );
	} else {
		deps = depList( '@stdlib/'+pkg, {
			'dev': false
		});
		deps = name2standalone( deps );
		devDeps = depList( '@stdlib/'+pkg, {
			'dev': true
		});
		devDeps = name2standalone( devDeps );
	}

	command = 'grep -r proxyquire '+dist+' | wc -l';
	debug( 'Count the number of lines including `proxyquire`: %s', command );
	nLines = shell( command ).toString();
	if ( parseInt( nLines, 10 ) > 0 && !contains( devDeps, 'proxyquire' ) ) {
		// Case: `proxyquire` is used outside of package code, e.g. in test fixtures, and has to be separately included in the list of development dependencies
		devDeps.push( 'proxyquire' );
	}
	triggerRelease = (
		releaseType === 'patch' ||
		releaseType === 'minor' ||
		releaseType === 'major'
	);
	if ( triggerRelease ) {
		version = semver.inc( version, releaseType );
	}
	debug( 'Copying and populating README.md file...' );
	readmePath = join( dist, 'README.md' );
	readme = readFileSync( readmePath, 'utf-8' );
	extractCLI = !isTopLevelNS && RE_CLI_USAGE_SECTION.test( readme );

	readme = replace( readme, RE_CLI_USAGE_SECTION, replacer );
	readme = replace( readme, RE_C_USAGE_SECTION, replacer );
	readme = replace( readme, RE_USAGE_SECTION, replacer );

	about = readFileSync( join( __dirname, 'templates', 'about_details.txt' ), 'utf-8' );
	readme = replace( readme, /\n#/, '\n\n'+about+'\n\n#' );

	badges = '[![NPM version][npm-image]][npm-url]';
	badges += ' ';
	if ( contains( devDeps, 'tape' ) ) {
		badges += '[![Build Status][test-image]][test-url]';
		badges += ' ';
		badges += '[![Coverage Status][coverage-image]][coverage-url]';
		badges += ' ';
	}
	badges += '<!-- ';
	badges += '[![dependencies][dependencies-image]][dependencies-url]';
	badges += ' -->';
	readme = replace( readme, /\n>/, '\n'+badges+'\n\n>' );
	readme = replace( readme, '\'@stdlib/'+pkg, '\'@stdlib/'+distPkg );

	branch = ( triggerRelease ) ? 'v'+version : 'main';
	if ( contains( readme, '<section class="links">' ) ) {
		readme = replace( readme, '<section class="links">', mainRepoSection( customLicense, branch, !noBundles, extractCLI ) );
	} else {
		readme += mainRepoSection( customLicense, branch, !noBundles, extractCLI );
		readme += '\n\n';
		readme += '</section>';
		readme += '\n\n';
		readme += '<!-- /.links -->';
	}
	readme = replace( readme, '<pkg>', distPkg );
	writeFileSync( readmePath, readme );

	opts = {
		'cwd': dist
	};
	command = [
		'find . -type f -name \'*.md\' -print0 ', // Find all regular Markdown files in the destination directory and print their full names to standard output...
		'| xargs -0 ', // Convert standard input to the arguments for following `sed` command...
		'sed -Ei ', // Edit files in-place without creating a backup...
		'\'s/',
		'(@stdlib\\/'+distPkg+')([^:]*)\\]: https.*$', // Match start of internal package link until end of line...
		'/',
		'\\1\\2]: https:\\/\\/github.com\\/stdlib-js\\/'+distPkg+'\\/tree\\/main\\2', // Replacement string generated via back-referencing the two created capture groups...
		'/g\'' // Replace all occurrences and not just the first...
	].join( '' );
	debug( 'Executing command: %s', command );
	shell( command, opts );

	command = [
		'find . -type f -name \'*.md\' -print0 ', // Find all regular Markdown files in the destination directory and print their full names to standard output...
		'| xargs -0 ', // Convert standard input to the arguments for following `sed` command...
		'sed -Ei ', // Edit files in-place without creating a backup...
		'"/',
		'^[^:]+: https:\\/\\/github.com\\/stdlib-js\\/stdlib\\/tree\\/develop\\/lib\\/node_modules\\/%40stdlib\\/', // Match start of external `@stdlib` package link (as internal ones are already processed) until end of line...
		'/ ',
		[
			'{',
			'    h', // Copy pattern space to hold space...
			'    s/:.*/: https:\\/\\/github.com\\/stdlib-js\\//', // Replace everything after the colon in the matched pattern with the beginning of new replacement URL...
			'    x', // Exchange the contents of the hold and pattern spaces...
			'    s/[^:]+: https:\\/\\/github.com\\/stdlib-js\\/stdlib\\/tree\\/develop\\/lib\\/node_modules\\/%40stdlib\\///', // Remove everything up to the beginning of the existing main project URL in the pattern space...
			'    s/\\//-/g', // Replace all occurrences of `/` with `-`...
			'    H', // Append pattern space to hold space...
			'    g', // Copy hold space to pattern space...
			'    s/\\n//', // Remove newline character added when appending pattern space to hold space
			'}'
		].join( '\n' ),
		'"'
	].join( '' );
	debug( 'Executing command: %s', command );
	shell( command, opts );

	if ( isTopLevelNS ) {
		// Rewrite internal packages as relative paths outside of documentation:
		for ( i = 0; i < MAX_TREE_DEPTH; i++ ) {
			command = [
				'find . -mindepth '+(1+i)+' -maxdepth '+(2+i)+' -type f \\( -name \'*.[jt]s\' \\) -print0 ', // Find all JavaScript and TypeScript files in the destination directory at the respective depth and print their full names to standard output...
				'| xargs -0 ', // Convert standard input to the arguments for following `sed` command...
				'sed -Ei ', // Edit files in-place without creating a backup...
				'"/',
				'\'@stdlib\\/types', // Skip over `@stdlib/types`...
				'/b; ',
				'/',
				'^[^\\*].+\'@stdlib\\/'+pkg, // Match internal packages outside of JSDoc comments...
				'/',
				[
					'{',
					'    s/\'@stdlib\\/'+pkg+'(.+)/\'.'+repeat( '\\/..', i+1 )+'\\1/', // Replace the start of internal package requires with a relative path of the respective depth
					'}'
				].join( '\n' ),
				'"'
			].join( '' );
			debug( 'Executing command: %s', command );
			try {
				shell( command, opts );
			} catch ( err ) {
				// Break out of loop in case of no input files...
				debug( 'Encountered an error: %s', err.message );
				break;
			}
		}
	}
	else {
		command = [
			'find . -type f \\( -name \'*.[jt]s\' -o -name \'*.md\' -o -name \'cli\' -o -name \'*.js.txt\' \\) -print0 ', // Find all JavaScript and TypeScript files in the destination directory and print their full names to standard output...
			'| xargs -0 ', // Convert standard input to the arguments for following `sed` command...
			'sed -Ei ', // Edit files in-place without creating a backup...
			'"/',
			'\'@stdlib\\/types', // Skip over `@stdlib/types`...
			'/b; ',
			'/',
			'\\/\\/ returns', // Skip over `// returns` annotations...
			'/b; ',
			'/',
			'\'@stdlib\\/', // Match `@stdlib` packages...
			'/ ',
			[
				'{',
				'    h', // Copy pattern space to hold space...
				'    s/^.+(\'.*$)/\\1/', // Remove everything before the last single quote
				'    x', // Exchange the contents of the hold and pattern spaces...
				'    s/\'[^\']*$//', // Remove everything after the last single quote
				'    s/\\//-/2g', // Replace any but the first occurrence of `/` with `-`...
				'    s/-data-([^\']*[.][^\']*)/\\/data\\/\\1/', // Revert back to backslashes for part of require path loading files from a package's `data` directory
				'    G', // Append hold space to pattern space...
				'    s/\\n//', // Remove newline character added when appending hold space to pattern space
				'}'
			].join( '\n' ),
			'"'
		].join( '' );
		debug( 'Executing command: %s', command );
		shell( command, opts );

		// Rewrite related packages in READMEs to point to standalone packages:
		command = [
			'find . -type f -name \'*.md\' ', // Find all Markdown files in the destination directory and print their full names to standard output...
			'-exec ', // Convert standard input to the arguments for following `sed` command...
			'sed -i ', // Edit files in-place...
			'\'',
			's/`@stdlib\\/\\([^/]*\\)\\/\\(.*\\)/`@stdlib\\/\\1-\\2/g', // Replace all forward slashes in package names except the first one...
			'\'',
			' {} +'
		].join( '' );
		debug( 'Executing command: %s', command );
		shell( command, opts );

		command = [
			'find . -type f -name \'*.js\' -print0 ', // Find all JavaScript files in the destination directory and print their full names to standard output...
			'| xargs -0 ', // Convert standard input to the arguments for following `sed` command...
			'sed -Ei ', // Edit files in-place without creating a backup...
			'"/',
			'@module @stdlib\\/', // Match @stdlib packages in JSDoc @module comment...
			'/s/',
			'\\/',
			'/',
			'-',
			'/2g"' // Replace all forward slashes in package name except the first one...
		].join( '' );
		debug( 'Executing command: %s', command );
		shell( command, opts );

		command = [
			'find . -type f -name \'include.gypi\' -print0 ', // Find all `include.gypi` files in the destination directory and print their full names to standard output...
			'| xargs -r -0 ', // Convert standard input to the arguments for following `sed` command...
			'sed -Ei ', // Edit files in-place without creating a backup...
			'"s/',
			'@stdlib\\/utils\\/library-manifest',
			'/',
			'@stdlib\\/utils-library-manifest', // Replace with standalone `library-manifest` package
			'/"'
		].join( '' );
		debug( 'Executing command: %s', command );
		shell( command, opts );

		command = [
			'find . -type f -name \'manifest.json\' -print0 ', // Find all `manifest.json` files in the destination directory and print their full names to standard output...
			'| xargs -r -0 ', // Convert standard input to the arguments for following `sed` command if `find` returns output...
			'sed -Ei ', // Edit files in-place without creating a backup...
			'"/',
			'@stdlib\\/[^ ]+', // Match @stdlib package names in dependencies
			'/s/',
			'\\/',
			'/',
			'-',
			'/2g"' // Replace all forward slashes in package names except the first one...
		].join( '' );
		debug( 'Executing command: %s', command );
		shell( command, opts );
	}
	pkgJSON.homepage = 'https://stdlib.io';
	pkgJSON.repository = {
		'type': 'git',
		'url': 'git://github.com/stdlib-js/'+distPkg+'.git'
	};

	// Ensure `npm install` does not automatically build a native add-on...
	if ( pkgJSON.gypfile ) {
		// TODO: consider removing this once we have determined our native add-on story for individual packages
		pkgJSON.gypfile = false;
	}
	pkgJSON.version = version;
	pkgJSON.funding = FUNDING;
	pkgJSON = populateDeps( pkgJSON, deps, devDeps, mainJSON, isTopLevelNS );
	fs.mkdirSync( join( dist, '.github', 'workflows' ), {
		'recursive': true
	});
	if ( isTopLevelNS ) {
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_publish_toplevel.yml.txt' ), join( dist, '.github', 'workflows', 'publish.yml' ) );
	} else {
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_publish.yml.txt' ), join( dist, '.github', 'workflows', 'publish.yml' ) );
		if ( extractCLI ) {
			fs.copyFileSync( join( __dirname, 'templates', 'workflow_publish_cli.yml.txt' ), join( dist, '.github', 'workflows', 'publish_cli.yml' ) );
		}
	}
	schedule = cronSchedule( '@stdlib/'+pkg );

	workflow = readFileSync( join( __dirname, 'templates', 'workflow_test_install.yml.txt' ), 'utf8' );
	workflow = replace( workflow, '{{cron}}', schedule );
	writeFileSync( join( dist, '.github', 'workflows', 'test_install.yml' ), workflow );

	workflow = readFileSync( join( __dirname, 'templates', 'workflow_npm_downloads.yml.txt' ), 'utf8' );
	workflow = replace( workflow, '{{cron}}', schedule );
	writeFileSync( join( dist, '.github', 'workflows', 'npm_downloads.yml' ), workflow );

	if ( !noBundles ) {
		if ( extractCLI ) {
			fs.copyFileSync( join( __dirname, 'templates', 'workflow_productionize_cli.yml.txt' ), join( dist, '.github', 'workflows', 'productionize.yml' ) );
		} else {
			fs.copyFileSync( join( __dirname, 'templates', 'workflow_productionize.yml.txt' ), join( dist, '.github', 'workflows', 'productionize.yml' ) );
		}
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_test_bundles.yml.txt' ), join( dist, '.github', 'workflows', 'test_bundles.yml' ) );
	}
	workflowPath = join( dist, '.github', 'workflows', 'close_pull_requests.yml' );
	writeFileSync( workflowPath, replace( WORKFLOW_CLOSE_PULLS, '<pkg-path>', pth ) );
	if ( contains( devDeps, 'tape' ) ) {
		workflow = readFileSync( join( __dirname, 'templates', 'workflow_test.yml.txt' ), 'utf8' );
		workflow = replace( workflow, '{{cron}}', schedule );
		writeFileSync( join( dist, '.github', 'workflows', 'test.yml' ), workflow );

		pkgJSON.scripts[ 'test' ] = 'make test';
		pkgJSON.scripts[ 'test-cov' ] = 'make test-cov';

		pkgJSON.devDependencies[ 'istanbul' ] = '^0.4.1';
		pkgJSON.devDependencies[ 'tap-min' ] = 'git+https://github.com/Planeshifter/tap-min.git';
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_test_coverage.yml.txt' ), join( dist, '.github', 'workflows', 'test_coverage.yml' ) );
	}
	if ( existsSync( join( dist, 'examples' ) ) ) {
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_examples.yml.txt' ), join( dist, '.github', 'workflows', 'examples.yml' ) );
		pkgJSON.scripts.examples = 'make examples';
	}
	if ( contains( devDeps, '@stdlib/bench' ) ) {
		fs.copyFileSync( join( __dirname, 'templates', 'workflow_benchmark.yml.txt' ), join( dist, '.github', 'workflows', 'benchmark.yml' ) );
		pkgJSON.scripts.benchmark = 'make benchmark';

		if ( !isTopLevelNS ) {
			// Replace `@stdlib/bench` with `@stdlib/bench-harness` in standalone packages:
			command = 'find '+dist+' -type f -name \'*.js\' -print0 | xargs -0 sed -i "s/\'@stdlib\\/bench\'/\'@stdlib\\/bench-harness\'/g"';
			shell( command );
			pkgJSON.devDependencies[ '@stdlib/bench-harness' ] = memoizedNPMversionForDevDeps( '@stdlib/bench-harness' );
			delete pkgJSON.devDependencies[ '@stdlib/bench' ];
		}
	}
	fs.copyFileSync( join( __dirname, 'templates', 'workflow_cancel.yml.txt' ), join( dist, '.github', 'workflows', 'cancel.yml' ) );

	workflow = readFileSync( join( __dirname, 'templates', 'workflow_test_published_package.yml.txt' ), 'utf8' );
	workflow = replace( workflow, '{{cron}}', schedule );
	writeFileSync( join( dist, '.github', 'workflows', 'test_published_package.yml' ), workflow );

	// Write the current date to the `.keepalive` file...
	if ( flags[ 'keep-alive' ] ) {
		fs.writeFileSync( join( dist, '.github', '.keepalive' ), new Date().toISOString() + '\n' );
	}

	fs.copyFileSync( join( __dirname, 'templates', 'CODE_OF_CONDUCT.md.txt' ), join( dist, 'CODE_OF_CONDUCT.md' ) );
	fs.copyFileSync( join( __dirname, 'templates', 'CONTRIBUTING.md.txt' ), join( dist, 'CONTRIBUTING.md' ) );

	if ( extractCLI ) {
		writeFileSync( join( dist, 'branches.md' ), replace( replace( BRANCHES_WITH_CLI, '<pkg-path>', pth ), '<pkg>', distPkg ) );
	} else {
		writeFileSync( join( dist, 'branches.md' ), replace( replace( BRANCHES, '<pkg-path>', pth ), '<pkg>', distPkg ) );
	}

	mdPath = join( dist, '.github', 'PULL_REQUEST_TEMPLATE.md' );
	writeFileSync( mdPath, replace( PULL_REQUEST_TEMPLATE, '<pkg-path>', pth ) );

	// Add `@stdlib/error-tools-fmtprodmsg` in package.json if the package depends on `@stdlib/string-format`:
	if ( pkgJSON.dependencies[ '@stdlib/string-format' ] ) {
		fmtProdMsgVersion = memoizedNPMversionForDeps( '@stdlib/error-tools-fmtprodmsg' );
		pkgJSON.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = fmtProdMsgVersion;
		deps.push( '@stdlib/error-tools-fmtprodmsg' );
	}
	debug( 'Saving `package.json` file...' );
	writeFileSync( pkgJsonPath, JSON.stringify( pkgJSON, null, '  ' ).concat( '\n' ) );

	if ( !isTopLevelNS ) {
		// Minify, bundle, and save files to `dist` subdirectory:
		try {
			command = 'mkdir dist';
			shell( command, opts );
			command = [
				'npx esbuild lib/index.js --bundle --format=cjs --target=es5',
				'--sourcemap --minify --platform=node --outfile=dist/index.js',
				'--external:'+deps.join( ' --external:' )
			].join( ' ' );
			debug( 'Executing command: %s', command );
			shell( command, opts );
		} catch ( error ) {
			debug( 'Encountered an error when attempting to bundle the package: %s', error.message );

			// Copy all source files to the `dist` subdirectory to proceed without bundling:
			command = 'cp -r lib/* dist';
			shell( command, opts );
		}
		// Apply code transformations:
		jscodeshift = join( rootDir(), 'node_modules', '.bin', 'jscodeshift' );
		command = 'STDLIB_INPUT_SOURCE_MAP=\'./dist/index.js.map\' STDLIB_PKG=\'@stdlib/'+distPkg+'\' '+jscodeshift+' ./dist/index.js -t '+join( __dirname, 'transform.js' );
		debug( 'Executing command: %s', command );
		shell( command, opts );
		try {
			// Extract the alias from the Typescript definition file (after `export =` but before the semicolon):
			command = 'grep -oP \'(?<=export = ).*?(?=;)\' docs/types/index.d.ts';
			alias = trim( shell( command, opts ).toString() );

			// Create the contents of a `index.d.ts` file in `dist` subdirectory that reexports `docs/types/index.d.ts` (we don't want to duplicate type definitions, so we just reexport them):
			contents = [
				'/// <reference path="../docs/types/index.d.ts" />',
				'import '+alias+' from \'../docs/types/index\';',
				'export = '+alias+';'
			].join( '\n' );
			writeFileSync( join( dist, 'dist', 'index.d.ts' ), contents );
		} catch ( error ) {
			debug( 'Encountered an error when attempting to extract the alias from the Typescript definition file: %s', error.message );
		}
		// Add test file(s) for `dist` builds:
		try {
			command = 'mkdir -p test/dist';
			shell( command, opts );
			fs.copyFileSync( join( __dirname, 'templates', 'test_dist_test.js.txt' ), join( dist, 'test', 'dist', 'test.js' ) );
		} catch ( error ) {
			debug( 'Encountered an error when attempting to copy a boilerplate test file to `dist`: %s', error.message );
		}
		// Add `dist` directory to `package.json`:
		if ( pkgJSON.directories ) {
			pkgJSON.directories.dist = './dist';
		}
	}

	if ( flags[ 'skip-upload' ] ) {
		return invokeCallback( null, 'skipped' );
	}
	ghpagesOpts = {
		'branch': 'main',
		'dotfiles': true,
		'src': [
			'**/*',
			'!**/.cache/**'
		],
		'repo': 'https://'+ ENV.GITHUB_TOKEN + '@github.com/stdlib-js/' + distPkg,
		'user': {
			'name': 'stdlib-bot',
			'email': 'noreply@stdlib.io'
		},
		'history': true,
		'beforeAdd': updatePermissions
	};
	if ( triggerRelease ) {
		ghpagesOpts.tag = branch;
		ghpagesOpts.message = 'Release v'+version;
	} else {
		ghpagesOpts.message = 'Auto-generated commit';
	}
	if ( repoExists ) {
		console.log( 'Publishing '+dist+' to GitHub...' );
		if ( triggerRelease ) {
			ghpages.publish( dist, ghpagesOpts, publishToNPM );
		} else {
			ghpages.publish( dist, ghpagesOpts, invokeCallback );
		}
		if ( flags[ 'overwrite-topics' ] ) {
			topics( 'stdlib-js/' + distPkg, createTopics( pkgJSON.keywords ) );
		}
	} else {
		console.log( 'Creating new remote repository: stdlib-js/'+distPkg );
		createRepo( distPkg, {
			'org': 'stdlib-js',
			'desc': pkgJSON.description,
			'homepage': 'https://github.com/stdlib-js/stdlib',
			'issues': false,
			'wiki': false,
			'projects': false,
			'private': false,
			'token': ENV.GITHUB_TOKEN,
			'allowSquashMerge': true,
			'allowRebaseMerge': false,
			'allowMergeCommit': false
		}, onRepoCreation );
	}

	/**
	* Publishes the package to npm.
	*
	* @private
	*/
	function publishToNPM() {
		var command;
		var escaped;
		var cliPkg;
		var found;
		var dep;

		console.log( 'Publishing '+dist+' to npm...' );
		pkgJSON = populateDeps( pkgJSON, deps, devDeps, mainJSON, false );

		command = 'rm -f docs/repl.txt && rm -f docs/types/test.ts';
		shell( command, opts );
		if ( extractCLI ) {
			// Delete the `bin` field from the `package.json` file:
			delete pkgJSON.bin;

			// Delete files:
			command = 'rm -rf ./bin/cli test/test.cli.js etc/cli_opts.json docs/usage.txt';
			shell( command, opts );

			// Remove CLI section:
			command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe "s/(\\* \\* \\*\n+)?<section class=\\"cli\\">[\\s\\S]+?<\\!\\-\\- \\/.cli \\-\\->//"';
			shell( command, opts );

			// Add entry for CLI package to "See Also" section of README.md:
			cliPkg = '@stdlib/' + distPkg + '-cli';
			cliPkg = replace( cliPkg, '/', '\\/' );
			cliPkg = replace( cliPkg, '@', '\\@' );
			command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe "s/<section class=\\"related\\">(?:\n\n\\* \\* \\*\n\n## See Also\n\n)?/<section class=\\"related\\">\n\n## See Also\n\n-   <span class=\\"package-name\\">[\\`'+cliPkg+'\\`]['+cliPkg+']<\\/span><span class=\\"delimiter\\">: <\\/span><span class=\\"description\\">CLI package for use as a command-line utility.<\\/span>\n/"';
			shell( command, opts );

			// Add link definition for CLI package to README.md:
			command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe "s/<section class=\\"links\\">/<section class=\\"links\\">\n\n['+cliPkg+']: https:\\/\\/www.npmjs.com\\/package\\/'+cliPkg+'/"';
			shell( command, opts );
		}

		if ( !isTopLevelNS ) {
			// For all dependencies, check in *.js files if they are used in what will be published to npm; if not, remove them:
			for ( dep in pkgJSON.dependencies ) {
				if ( hasOwnProp( pkgJSON.dependencies, dep ) ) {
					escaped = replace( dep, '@', '\\@' );
					escaped = replace( escaped, '/', '\\/' );
					command = [
						'if ! find lib -name "*.js" -exec grep -q "'+escaped+'" {} + && ! grep -q -s "'+escaped+'" manifest.json && ! grep -q -s "'+escaped+'" include.gypi; then',
						'  printf "false"',
						'else',
						'  printf "true"',
						'fi'
					].join( '\n' );
					found = shell( command, opts ).toString();
					if ( found === 'false' && dep !== '@stdlib/error-tools-fmtprodmsg' ) {
						delete pkgJSON.dependencies[ dep ];
					}
				}
			}
		}

		debug( 'Replace GitHub MathJax equations with SVGs...' );
		command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe \'s/```math\\n([\\s\\S]+?)\\n```\\n\\n//g\'';
		shell( command, opts );
		command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe \'s/<!-- <div class="equation"(.*)(<\\/div>\\s*-->)/<div class="equation"$1<\\/div>/sg\'';
		shell( command, opts );

		debug( 'Replace GitHub links to individual packages with npm links...' );
		command = 'find . -type f -name \'*.md\' -print0 | xargs -0 sed -Ei \'/tree\\/main/b; s/@stdlib\\/([^:]*)\\]: https:\\/\\/github.com\\/stdlib-js/@stdlib\\/\\1\\]: https:\\/\\/www.npmjs.com\\/package\\/@stdlib/g\'';
		shell( command, opts );

		debug( 'Replace list with links to other branches from installation section...' );
		command = 'find . -type f -name \'*.md\' -print0 | xargs -0 perl -0777 -i -pe "s/\\`\\`\\`\n\nAlternatively,[^<]+<\\/section>/\\`\\`\\`\n\n<\\/section>/"';
		shell( command, opts );

		// Set `scripts` and `devDependencies` to an empty object and update `directories`:
		pkgJSON.scripts = {};
		pkgJSON.devDependencies = {};
		if ( pkgJSON.directories ) {
			delete pkgJSON.directories.benchmark;
			delete pkgJSON.directories.example;
			delete pkgJSON.directories.test;
		}
		writeFileSync( pkgJsonPath, JSON.stringify( pkgJSON, null, '  ' ).concat( '\n' ) );

		shell( 'npm publish --access public', opts );
		invokeCallback();
	}

	/**
	* Adds executable permission to `bin/cli` files.
	*
	* @private
	* @param {Object} git - `git` class instance
	*/
	function updatePermissions( git ) {
		shell( 'find '+git.cwd+' -regex \'.*/bin/cli\' -print0 | xargs -r -0 chmod +x' );
	}

	/**
	* Replacer function for inserting an install section before a usage section.
	*
	* @private
	* @param {string} match - entire match
	* @param {string} p1 - first capture group
	* @param {string} p2 - second capture group
	* @returns {string} replacement
	*/
	function replacer( match, p1, p2 ) {
		var out;

		if ( isString( p1 ) ) {
			if ( startsWith( p1, '## CLI' ) ) {
				return p1 + CLI_INSTALLATION_SECTION + ( p2 || '\n<!-- CLI usage documentation. -->\n' ) + '\n<section class="usage">';
			}
			if ( startsWith( p1, '<!-- C usage documentation. -->' ) ) {
				return p1 + '<section class="usage">';
			}
		}
		if ( noBundles ) {
			out = INSTALLATION_SECTION_BASIC;
		} else {
			out = INSTALLATION_SECTION_BUNDLES;
			out = out.replace( '<cli>', ( extractCLI ) ? INSTALLATION_SECTION_BUNDLES_CLI : '' );
		}
		out += '\n<section class="usage">';
		return out;
	}

	/**
	* Callback invoked upon pushing package contents to remote GitHub repository.
	*
	* @private
	* @param {(Error|null)} error - encountered error
	* @param {string} [status] - publish status
	* @returns {void}
	*/
	function invokeCallback( error, status ) {
		var pkgInfo = {
			'name': pkgJSON && pkgJSON.name,
			'description': pkgJSON && pkgJSON.description,
			'status': status || ( ( error )? 'failure' : 'success' )
		};
		clbk( error, pkgInfo );
	}

	/**
	* Callback invoked upon creating GitHub repository.
	*
	* @private
	* @param {(Error|null)} error - encountered error
	* @param {Object} repo - repo data
	* @param {Object} info - rate limit info
	* @returns {void}
	*/
	function onRepoCreation( error, repo, info ) {
		var currentTime;
		var waitTime;
		if ( error ) {
			return console.error( error );
		}
		console.log( 'GitHub repository '+repo.full_name+' has been successfully created.' );
		console.log( 'Rate limit information: '+JSON.stringify( info ) );

		topics( 'stdlib-js/' + distPkg, createTopics( pkgJSON.keywords ) );
		if ( info.remaining === 0 ) {
			currentTime = new Date().getTime();
			waitTime = new Date( info.reset * 1000 ).getTime() - currentTime;
			ghpages.publish( dist, ghpagesOpts, withDelay );
		} else {
			ghpages.publish( dist, ghpagesOpts, invokeCallback );
		}

		/**
		* Invokes callback for once pushing package contents to remote GitHub repository after a specified delay.
		*
		* @private
		* @param {(Error|null)} err - error object or `null`
		* @returns {void}
		*/
		function withDelay( err ) {
			if ( err ) {
				return console.log( err );
			}
			console.log( 'Waiting '+waitTime+'ms before moving to next package...' );
			setTimeout( invokeCallback, waitTime );
		}
	}
}


// MAIN //

/**
* Main execution sequence.
*
* @private
* @throws {Error} unexpected error
* @returns {void}
*/
function main() {
	var repeatedTry;
	var fpath;
	var pkgs;
	var idx;
	var pkg;
	var tmp;
	var err;
	var re;
	var i;

	if ( !args || args.length === 0 ) {
		debug( 'Creating an ordered package list...' );
		pkgs = toposort({
			'ignore': [
				'**/_tools/**'
			]
		});
		if ( pkgs instanceof Error ) {
			debug( 'Unable to create an ordered package list. Error: %s', pkgs.message );
			throw pkgs;
		}
		debug( 'Successfully created an ordered package list.' );

		debug( 'Writing list to file...' );
		fpath = join( tmpdir(), 'stdlib_ordered_pkg_list.json' );
		err = writeFileSync( fpath, JSON.stringify( pkgs, null, '  ' )+'\n', {
			'encoding': 'utf8'
		});
		if ( err instanceof Error ) {
			debug( 'Unable to write list to file. Error: %s', err.message );
			throw err;
		}
		debug( 'Successfully wrote list to file.' );

		pkgs = pkgs.slice( START_PKG_INDEX, END_PKG_INDEX + 1 );
		if ( flags[ 'keep-alive' ] ) {
			pkgs = sample( pkgs, {
				'size': KEEP_ALIVE_SAMPLE_SIZE,
				'replace': false
			});
		}
		for ( i = 0; i < pkgs.length; i++ ) {
			pkgs[ i ] = replace( pkgs[ i ], '@stdlib/', '' );
		}
	} else {
		pkgs = args;
		for ( i = 0; i < pkgs.length; i++ ) {
			pkgs[ i ] = replace( pkgs[ i ], '@stdlib/', '' );
			pkgs[ i ] = trim( pkgs[ i ] );
		}
	}

	// Filter out packages:
	tmp = [];
	for ( i = 0; i < pkgs.length; i++ ) {
		if (
			!startsWith( pkgs[ i ], '_tools' ) && // Do not publish internal `stdlib` tooling packages
			!startsWith( pkgs[ i ], 'plot/' ) && // Do not publish individual `plot` package but do publish overall namespace
			!startsWith( pkgs[ i ], 'strided/common' ) // Do not publish namespace slated to go away
		) {
			tmp.push( pkgs[ i ] );
		}
	}
	pkgs = tmp;
	if ( flags[ 'skip-individual' ] ) {
		console.log( 'Do not publish individual packages...' );
		tmp = [];
		for ( i = 0; i < pkgs.length; i++ ) {
			if ( !contains( pkgs[ i ], '/' ) ) {
				tmp.push( pkgs[ i ] );
			}
		}
		pkgs = tmp;
	}
	if ( flags[ 'skip-toplevel' ] ) {
		console.log( 'Do not publish toplevel packages...' );
		tmp = [];
		for ( i = 0; i < pkgs.length; i++ ) {
			if ( contains( pkgs[ i ], '/' ) ) {
				tmp.push( pkgs[ i ] );
			}
		}
		pkgs = tmp;
	}
	if ( flags[ 'pattern' ] ) {
		console.log( 'Only publish packages matching the following pattern: '+flags[ 'pattern' ] );
		tmp = [];
		re = reFromString( rescape( '/'+flags[ 'pattern' ]+'/' ) );
		for ( i = 0; i < pkgs.length; i++ ) {
			if ( re.test( pkgs[ i ] ) ) {
				tmp.push( pkgs[ i ] );
			}
		}
		pkgs = tmp;
	}
	console.log( 'Publishing %d `stdlib` packages...', pkgs.length );
	idx = 0;
	pkg = pkgs[ idx ];
	console.log( 'Starting by processing the following package: %s', pkg );

	cleanCache();

	debug( 'Clean-up existing build directory...' );
	fs.rmSync( join( mainDir, 'build' ), {
		'recursive': true,
		'force': true
	});

	publish( pkg, onCallback );

	/**
	* Callback invoked once pushing package contents to remote GitHub repository.
	*
	* @private
	* @param {(Error|null)} err - error object or `null`
	* @param {Object} pkgInfo - package information
	* @returns {void}
	*/
	function onCallback( err, pkgInfo ) {
		var fpath;
		if ( err && !repeatedTry ) {
			console.log( err );
			cleanCache();
			console.log( 'Trying again once more to process the following package: %s', pkg );
			repeatedTry = true;
			publish( pkg, onCallback );
		} else {
			if ( pkgInfo.status === 'skipped' ) {
				console.log( 'Skipped publishing package...' );
				pkgs[ idx ] = null;
			}
			else if ( pkgInfo.status === 'success' ) {
				console.log( 'Successfully published package %s to remote GitHub repository', pkgInfo.name );
				pkgs[ idx ] = pkgInfo;
			}
			idx += 1;
			pkg = pkgs[ idx ];
			repeatedTry = false;
			if ( pkg ) {
				console.log( 'Now processing the following package: %s', pkg );
				publish( pkg, onCallback );
			} else {
				console.log( 'All `stdlib` packages successfully pushed to GitHub...' );
				fpath = join( tmpdir(), 'stdlib_published_pkg_list.json' );
				writeFileSync( fpath, JSON.stringify( pkgs, null, '\t' ) );
			}
		}
	}
}

main();