docs: consolidated cli commands descriptions. Revised README (#878)

* docs: consolidated cli commands descriptions. Revised README

* docs: add description to noVerify flag. Add missing default parameter to --no-dependencies

* replace no-verify with allow-proposed-api flag for clarity

* add no-verify flag back for compatibility while hidden in the options list

* 💄

---------

Co-authored-by: João Moreno <[email protected]>

README.md

@@ -1,19 +1,21 @@
-# vsce
+# @vscode/vsce
 
 > _The Visual Studio Code Extension Manager_
 
 [![Build Status](https://dev.azure.com/monacotools/Monaco/_apis/build/status/npm/microsoft.vscode-vsce?repoName=microsoft%2Fvscode-vsce&branchName=main)](https://dev.azure.com/monacotools/Monaco/_build/latest?definitionId=446&repoName=microsoft%2Fvscode-vsce&branchName=main)
 [![Version](https://img.shields.io/npm/v/@vscode/vsce.svg)](https://npmjs.org/package/@vscode/vsce)
 
-## Requirements
+This tool assists in packaging and publishing Visual Studio Code extensions.
+
+Read the [**Documentation**](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) on the VS Code website.
 
-- [Node.js](https://nodejs.org/en/) at least `14.x.x`
+## Requirements
 
-Or simply [Docker](#usage-via-docker).
+[Node.js](https://nodejs.org/en/) at least `18.x.x`.
 
 ### Linux
 
-In order to save credentials safely, this project uses [keytar](https://www.npmjs.com/package/keytar) which uses `libsecret`, which you may need to install before publishing extensions. Setting the `VSCE_STORE=file` environment variable will revert back to the file credential store. Using the `VSCE_PAT` environment variable will also avoid using keytar.
+In order to save credentials safely, this project uses [`keytar`](https://www.npmjs.com/package/keytar) which uses `libsecret`, which you may need to install before publishing extensions. Setting the `VSCE_STORE=file` environment variable will revert back to the file credential store. Using the `VSCE_PAT` environment variable will also avoid using `keytar`.
 
 Depending on your distribution, you will need to run the following command:
 
@@ -24,46 +26,18 @@ Depending on your distribution, you will need to run the following command:
 
 ## Usage
 
-Install vsce globally:
-
 ```console
-npm install --global @vscode/vsce
+$ npx @vscode/vsce --version
 ```
 
-Verify the installation:
-
-```console
-vsce --version
-```
-
-`vsce` is meant to be mainly used as a command line tool. It can also be used a library since it exposes a small [API](https://github.com/microsoft/vscode-vsce/blob/main/src/api.ts). When using vsce as a library be sure to sanitize any user input used in API calls, as a security measurement.
-
-## Usage via Docker
-
-You can also build a container for running vsce:
-
-```console
-$ DOCKER_BUILDKIT=1 docker build --tag vsce "https://github.com/microsoft/vscode-vsce.git#main"
-```
-
-Validate the container:
-
-```console
-docker run --rm -it vsce --version
-```
-
-Publish your local extension:
-
-```console
-docker run --rm -it -v "$(pwd)":/workspace vsce publish
-```
+`@vscode/vsce` is meant to be mainly used as a command-line tool. It can also be used as a library since it exposes a small [API](https://github.com/microsoft/vscode-vsce/blob/main/src/api.ts). When using `@vscode/vsce` as a library, be sure to sanitize any user input used in API calls to prevent security issues.
 
 ## Configuration
 
 You can configure the behavior of `vsce` by using CLI flags (run `vsce --help` to list them all). Example:
 
 ```console
-vsce publish --baseImagesUrl https://my.custom/base/images/url
+$ npx @vscode/vsce publish --baseImagesUrl https://my.custom/base/images/url
 ```
 
 Or you can also set them in the `package.json`, so that you avoid having to retype the common options again. Example:
@@ -85,25 +59,19 @@ First clone this repository, then:
 
 ```console
 $ npm install
-
 $ npm run watch:build # or `watch:test` to also build tests
 ```
 
 Once the watcher is up and running, you can run out of sources with:
 
 ```console
-node vsce
+$ node vsce
 ```
 
 Tests can be executed with:
 
-```npm
+```console
 $ npm test
 ```
 
 > **Note:** [Yarn](https://www.npmjs.com/package/yarn) is required to run the tests.
-## About
-
-This tool assists in packaging and publishing Visual Studio Code extensions.
-
-Read the [**Documentation**](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) on the VS Code website.

src/main.ts

@@ -62,9 +62,9 @@ module.exports = function (argv: string[]): void {
 
 	program
 		.command('ls')
-		.description('Lists all the files that will be published')
+		.description('Lists all the files that will be published/packaged')
 		.option('--yarn', 'Use yarn instead of npm (default inferred from presence of yarn.lock or .yarnrc)')
-		.option('--no-yarn', 'Use npm instead of yarn (default inferred from lack of yarn.lock or .yarnrc)')
+		.option('--no-yarn', 'Use npm instead of yarn (default inferred from absence of yarn.lock or .yarnrc)')
 		.option<string[]>(
 			'--packagedDependencies <path>',
 			'Select packages that should be published only (includes dependencies)',
@@ -100,16 +100,16 @@ module.exports = function (argv: string[]): void {
 			'The GitLab branch used to infer relative links in README.md. Can be overridden by --baseContentUrl and --baseImagesUrl.'
 		)
 		.option('--no-rewrite-relative-links', 'Skip rewriting relative links.')
-		.option('--baseContentUrl <url>', 'Prepend all relative links in README.md with this url.')
-		.option('--baseImagesUrl <url>', 'Prepend all relative image links in README.md with this url.')
+		.option('--baseContentUrl <url>', 'Prepend all relative links in README.md with the specified URL.')
+		.option('--baseImagesUrl <url>', 'Prepend all relative image links in README.md with the specified URL.')
 		.option('--yarn', 'Use yarn instead of npm (default inferred from presence of yarn.lock or .yarnrc)')
-		.option('--no-yarn', 'Use npm instead of yarn (default inferred from lack of yarn.lock or .yarnrc)')
+		.option('--no-yarn', 'Use npm instead of yarn (default inferred from absence of yarn.lock or .yarnrc)')
 		.option('--ignoreFile <path>', 'Indicate alternative .vscodeignore')
 		.option('--no-gitHubIssueLinking', 'Disable automatic expansion of GitHub-style issue syntax into links')
 		.option('--no-gitLabIssueLinking', 'Disable automatic expansion of GitLab-style issue syntax into links')
 		// default must remain undefined for dependencies or we will fail to load defaults from package.json
 		.option('--dependencies', 'Enable dependency detection via npm or yarn', undefined)
-		.option('--no-dependencies', 'Disable dependency detection via npm or yarn')
+		.option('--no-dependencies', 'Disable dependency detection via npm or yarn', undefined)
 		.option('--pre-release', 'Mark this package as a pre-release')
 		.option('--allow-star-activation', 'Allow using * in activation events')
 		.option('--allow-missing-repository', 'Allow missing a repository URL in package.json')
@@ -189,10 +189,10 @@ module.exports = function (argv: string[]): void {
 			'--gitlabBranch <branch>',
 			'The GitLab branch used to infer relative links in README.md. Can be overridden by --baseContentUrl and --baseImagesUrl.'
 		)
-		.option('--baseContentUrl <url>', 'Prepend all relative links in README.md with this url.')
-		.option('--baseImagesUrl <url>', 'Prepend all relative image links in README.md with this url.')
+		.option('--baseContentUrl <url>', 'Prepend all relative links in README.md with the specified URL.')
+		.option('--baseImagesUrl <url>', 'Prepend all relative image links in README.md with the specified URL.')
 		.option('--yarn', 'Use yarn instead of npm (default inferred from presence of yarn.lock or .yarnrc)')
-		.option('--no-yarn', 'Use npm instead of yarn (default inferred from lack of yarn.lock or .yarnrc)')
+		.option('--no-yarn', 'Use npm instead of yarn (default inferred from absence of yarn.lock or .yarnrc)')
 		.option('--noVerify', 'Allow all proposed APIs (deprecated: use --allow-all-proposed-apis instead)')
 		.option('--allow-proposed-apis <apis...>', 'Allow specific proposed APIs')
 		.option('--allow-all-proposed-apis', 'Allow all proposed APIs')
@@ -262,53 +262,53 @@ module.exports = function (argv: string[]): void {
 
 	program
 		.command('unpublish [extensionid]')
-		.description('Unpublishes an extension. Example extension id: microsoft.csharp.')
+		.description('Unpublishes an extension. Example extension id: ms-vscode.live-server.')
 		.option('-p, --pat <token>', 'Personal Access Token')
-		.option('-f, --force', 'Forces Unpublished Extension')
+		.option('-f, --force', 'Skip confirmation prompt when unpublishing an extension')
 		.action((id, { pat, force }) => main(unpublish({ id, pat, force })));
 
 	program
 		.command('ls-publishers')
-		.description('List all known publishers')
+		.description('Lists all known publishers')
 		.action(() => main(listPublishers()));
 
 	program
 		.command('delete-publisher <publisher>')
-		.description('Deletes a publisher')
+		.description('Deletes a publisher from marketplace')
 		.action(publisher => main(deletePublisher(publisher)));
 
 	program
 		.command('login <publisher>')
-		.description('Add a publisher to the known publishers list')
+		.description('Adds a publisher to the list of known publishers')
 		.action(name => main(loginPublisher(name)));
 
 	program
 		.command('logout <publisher>')
-		.description('Remove a publisher from the known publishers list')
+		.description('Removes a publisher from the list of known publishers')
 		.action(name => main(logoutPublisher(name)));
 
 	program
 		.command('verify-pat [publisher]')
+		.description('Verifies if the Personal Access Token has publish rights for the publisher')
 		.option(
 			'-p, --pat <token>',
 			'Personal Access Token (defaults to VSCE_PAT environment variable)',
 			process.env['VSCE_PAT']
 		)
-		.description('Verify if the Personal Access Token has publish rights for the publisher.')
 		.action((name, { pat }) => main(verifyPat(pat, name)));
 
 	program
 		.command('show <extensionid>')
-		.option('--json', 'Output data in json format', false)
-		.description('Show extension metadata')
+		.description(`Shows an extension's metadata`)
+		.option('--json', 'Outputs data in json format', false)
 		.action((extensionid, { json }) => main(show(extensionid, json)));
 
 	program
 		.command('search <text>')
-		.option('--json', 'Output result in json format', false)
-		.option('--stats', 'Shows the extension rating and download counts', false)
+		.description('Searches extension gallery')
+		.option('--json', 'Output results in json format', false)
+		.option('--stats', 'Shows extensions rating and download count', false)
 		.option('-p, --pagesize [value]', 'Number of results to return', '100')
-		.description('search extension gallery')
 		.action((text, { json, pagesize, stats }) => main(search(text, json, parseInt(pagesize), stats)));
 
 	program.on('command:*', ([cmd]: string) => {
@@ -324,8 +324,7 @@ module.exports = function (argv: string[]): void {
 			const availableCommands = program.commands.map(c => c._name);
 			const suggestion = availableCommands.find(c => leven(c, cmd) < c.length * 0.4);
 
-			help = `${help}
-Unknown command '${cmd}'`;
+			help = `${help}\n Unknown command '${cmd}'`;
 
 			return suggestion ? `${help}, did you mean '${suggestion}'?\n` : `${help}.\n`;
 		});

src/publish.ts

@@ -56,6 +56,7 @@ export interface IPublishOptions {
 	 * Defaults to the stored one.
 	 */
 	readonly pat?: string;
+	readonly allowProposedApi?: boolean;
 	readonly noVerify?: boolean;
 	readonly allowProposedApis?: string[];
 	readonly allowAllProposedApis?: boolean;
@@ -130,6 +131,7 @@ export async function publish(options: IPublishOptions = {}): Promise<any> {
 export interface IInternalPublishOptions {
 	readonly target?: string;
 	readonly pat?: string;
+	readonly allowProposedApi?: boolean;
 	readonly noVerify?: boolean;
 	readonly allowProposedApis?: string[];
 	readonly allowAllProposedApis?: boolean;