feat: add shopware-cli documentation (#1657)

* feat: add shopware-cli documentation

* Update products/cli/project-commands/project-config-sync.md

Co-authored-by: Copilot <[email protected]>

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* fix: markdown errors

* fix: markdown errors

* fix: spellchecker issues

* docs: add bundle info

* fix: make markdown linter happy

* docs: add hint for worker

* feat: adopt dump page to new flags

* feat: add new environment variables to specify api connection

* feat: add project create version info

* feat: sort word list

* Textual update

* fix: comment stuff

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: su <[email protected]>
Co-authored-by: Su <[email protected]>

products/cli/extension-commands/admin-watcher.md

@@ -0,0 +1,34 @@
+---
+nav:
+  title: Standalone Admin Watcher
+  position: 3
+
+---
+
+# Standalone Admin Watcher
+
+::: info
+`shopware-cli extension admin-watch` can be different to the regular Admin Watcher. You can start the regular Admin Watcher with `shopware-cli project admin-watch`
+:::
+
+Shopware-CLI has an integrated Standalone Admin Watcher. This is useful if the regular Admin Watcher struggles with the amount of installed extensions and you only want to watch one single extension. The Standalone Watcher works by using the regular build Administration and injects only the changed files of the extension.
+
+Therefore the Watcher starts in few milliseconds and is very fast. Additionally, it can be targeted to an external Shopware 6 Instance to debug JavaScript or CSS changes with the external data.
+
+## Starting the Standalone Admin Watcher
+
+To start the Standalone Admin Watcher, you can use the following command:
+
+```bash
+shopware-cli extension admin-watch <path-to-extension> <url-to-shopware>
+```
+
+The first parameter is the **path to extension** you want to watch and the last parameter is the URL to the Shopware 6 instance. The URL must be reachable from the machine where the CLI is executed. You can watch also multiple extensions by providing multiple paths, but the last parameter must be the URL to the Shopware 6 instance.
+
+You can also pass **path of a Shopware project** to the command. In this case, the CLI will automatically detect the extensions.
+
+The listing port of the Admin Watcher can be changed with `--listen :<port>`.
+
+## Usage behind a proxy
+
+If you want to use the Standalone Admin Watcher behind a proxy, for example, SSL, you should set `--external-url` to the URL where the Admin Watcher will be reachable in the Browser.

products/cli/extension-commands/build.md

@@ -0,0 +1,171 @@
+---
+nav:
+  title: Building extensions and creating archives
+  position: 2
+
+---
+
+# Building extensions and creating archives
+
+Extensions consists of PHP Changes, JavaScript and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration your extension needs to provide the compiled assets.
+
+## Building an extension
+
+Shopware-CLI allows you to easily build the assets of an extension. To build an extension, you can use the following command:
+
+```bash
+shopware-cli extension build <path>
+```
+
+Shopware-CLI reads the `shopware/core` requirement from `composer.json` or `manifest.xml` and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a `.shopware-extension.yml` file.
+
+```yaml
+# .shopware-extension.yml
+build:
+  shopwareVersionConstraint: '6.6.9.0'
+```
+
+This only affects the build process and not on the installation of the extension. For full control you can also specify the environment variable `SHOPWARE_PROJECT_ROOT` pointing to a Shopware 6 project, and it will use that Shopware to build the extension assets.
+
+## Additional bundles
+
+If your plugin consists of multiple bundles, usually when you have implemented `getAdditionalBundles` in your `Plugin` class, you have to provide the path to the bundle you want to build in the config:
+
+```yaml
+# .shopware-extension.yml
+build:
+  extraBundles:
+    # Assumes the bundle name is the same as the directory name
+    - path: src/Foo
+    # Explictly specify the bundle name
+    - path: src/Foo
+      name: Foo
+```
+
+## Using esbuild for JavaScript Bundling
+
+::: warning
+Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension.
+:::
+
+Esbuild can be utilized for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.
+
+```yaml
+# .shopware-extension.yml
+build:
+  zip:
+    assets:
+      # Use esbuild for Administration
+      enable_es_build_for_admin: true
+      # Use esbuild for Storefront
+      enable_es_build_for_storefront: true
+```
+
+## Creating an archive
+
+To create an archive of an extension, you can use the following command:
+
+```bash
+shopware-cli extension zip <path>
+```
+
+The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a zip archive of the extension. The archive is placed in the current working directory.
+
+**By default the command picks the latest released git tag**, use `--disable-git` as flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using `--git-commit`.
+
+### Bundling composer dependencies
+
+Before Shopware 6.5, bundling the composer dependencies into the zip file is required. Shopware-CLI automatically runs `composer install` and removes duplicate composer dependencies to avoid conflicts.
+
+To disable this behavior, you can adjust the configuration:
+
+```yaml
+# .shopware-extension.yml
+build:
+  zip:
+    composer:
+      enabled: false
+```
+
+This is automatically disabled for plugins targeting Shopware 6.5 and above and `executeComposerCommands` should be used instead.
+
+### Delete files before zipping
+
+Shopware-CLI deletes a lot of known files before zipping the extension. If you want to delete more files, you can adjust the configuration:
+
+```yaml
+# .shopware-extension.yml
+build:
+  zip:
+    pack:
+      excludes:
+        paths:
+          - <path>
+```
+
+### JavaScript Build optimization
+
+If you bring additional NPM packages, make sure that you added only runtime dependencies to `dependencies` inside `package.json` and tooling to `devDependencies` and enabled `npm_strict` in the configuration:
+
+```yaml
+# .shopware-extension.yml
+build:
+  zip:
+    assets:
+      npm_strict: true
+```
+
+This skips unnecessary `npm install` and `npm ci` commands and only installs the runtime dependencies.
+
+### Release mode
+
+If you are building an archive for distribution, you can enable the release mode with the flag `--release`. This will remove the App secret from the `manifest.xml` and generate changelog files if enabled.
+
+The changelog generation can be enabled with the configuration:
+
+```yaml
+# .shopware-extension.yml
+changelog:
+  enabled: true
+```
+
+It utilizes the commits between the last tag and the current commit to generate the changelog. Additionally, it can be configured to filter commits and build the changelog differently.
+
+```yaml
+changelog:
+  enabled: true
+  # only the commits matching to this regex will be used
+  pattern: '^NEXT-\d+'
+  # variables allows to extract metadata out of the commit message
+  variables:
+    ticket: '^(NEXT-\d+)\s'
+  # go template for the changelog, it loops over all commits
+  template: |
+    {{range .Commits}}- [{{ .Message }}](https://issues.shopware.com/issues/{{ .Variables.ticket }})
+    {{end}}
+```
+
+This example checks that all commits in the changelog needs to start with `NEXT-` in the beginning. The `variables` section allows to extract metadata out of the commit message. The `template` is a go template which loops over all commits and generates the changelog.
+With the combination of `pattern`, `variables` and `template` we link the commit message to the Shopware ticket system.
+
+### Overwrites
+
+Extension configuration can be overwritten during the zipping process, allowing changes to aspects such as the version and app-related settings.
+
+```yaml
+shopware-cli extension zip --overwrite-version=1.0.0 <path>
+```
+
+Replaces the version in `composer.json` or `manifest.xml` with the given version.
+
+```yaml
+shopware-cli extension zip --overwrite-app-backend-url=https://example.com <path>
+```
+
+Replaces all external URLs in `manifest.xml` to that given URL.
+
+```yaml
+shopware-cli extension zip --overwrite-app-backend-secret=MySecret <path>
+```
+
+Replaces the App secret in `manifest.xml` with the given secret.

products/cli/extension-commands/extract-meta-data.md

@@ -0,0 +1,32 @@
+---
+nav:
+  title: Extracting Meta Data
+  position: 4
+
+---
+
+# Extracting Meta Data
+
+There are helpers in Shopware-CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version or the changelog for the automated release.
+
+## Extracting the version
+
+To extract the version of an extension, you can use the following command:
+
+```bash
+shopware-cli extension get-version <path>
+```
+
+The path can be absolute or relative to the current working directory. The command will output the version of the extension.
+
+## Extracting the changelog
+
+To extract the changelog of an extension, you can use the following command:
+
+```bash
+shopware-cli extension get-changelog <path>
+```
+
+The path can be absolute or relative to the current working directory. The command will output the changelog of the extension.
+
+It will output always the English changelog.

products/cli/extension-commands/validation.md

@@ -0,0 +1,42 @@
+---
+nav:
+  title: Extension Validation
+  position: 1
+
+---
+
+# Extension Validation
+
+Shopware-CLI has a built-in validation for extensions. This is useful in your CI/CD pipeline to validate the extension before you release it.
+
+## Validating an extension
+
+To validate an extension, you can use the following command:
+
+```bash
+shopware-cli extension validate <path>
+```
+
+The path can be absolute or relative to the directory containing the extension or the zip file. The command exists with a non-zero exit code if the validation fails with a error level message.
+
+## What is validated?
+
+- The `composer.json` has an `shopware/core` requirement and constraint is parsable
+- The extension metadata is filled with:
+  - `name`
+  - `label` (German and English)
+  - `description` (German and English) and longer than 150 characters and shorter than 185 characters
+- Translations have equality translated in the given languages
+- PHP can be correctly linted with the minimum PHP version
+- The `theme.json` can be parsed and included assets can be found
+
+## Supported PHP versions for linting
+
+Following PHP versions are supported for linting:
+
+- 7.3
+- 7.4
+- 8.1
+- 8.2
+
+These versions don't need to be installed locally, they are downloaded on demand and executed using WebAssembly without any dependencies.

products/cli/index.md

@@ -0,0 +1,18 @@
+---
+nav:
+  title: Shopware-CLI
+  position: 40
+
+---
+
+# Shopware-CLI
+
+Shopware-CLI is an open-source external command-line interface for Shopware 6. It provides a set of commands to interact with your Shopware instance, build extensions, dump databases and more. The CLI **is a external tool** and needs to be set up separately from your Shopware instance.
+
+The CLI consists of three main components:
+
+- Project commands: Commands to interact with your Shopware project
+- Extension commands: Commands to build Shopware extensions
+- Store commands: Commands to publish extensions to the Shopware Store or update
+
+If you want to use the CLI, you need to [install it first](installation.md) or take a look at each area of the CLI.