@automattic/vip 4.1.3 → 4.1.5

package/cmd/vip-next/pendo_wiring_test.go

@@ -0,0 +1,148 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/Automattic/vip/internal/auth"
+	"github.com/Automattic/vip/internal/keychain"
+	"github.com/Automattic/vip/internal/telemetry"
+	"github.com/spf13/cobra"
+)
+
+// The Pendo endpoint requires the same bearer as the command API. A payload-only
+// test with an always-200 server did not catch the missing authentication.
+func TestPendoUsesCommandSession(t *testing.T) {
+	for _, mode := range []string{"stored", "bypassed", "login"} {
+		t.Run(mode, func(t *testing.T) {
+			for _, name := range []string{"DO_NOT_TRACK", "GO_ENV", "NODE_ENV", "VIP_TOKEN_OVERRIDE", "WPVIP_DEPLOY_TOKEN", "VIP_PROXY", "vip_proxy", "VIP_USE_SYSTEM_PROXY"} {
+				t.Setenv(name, "")
+			}
+			raw := validBootstrapRaw(t, 10000)
+			accepted, rejected := 0, 0
+			pendo := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.Header.Get("Authorization") != "Bearer "+raw {
+					rejected++
+					w.WriteHeader(http.StatusUnauthorized)
+					return
+				}
+				accepted++
+			}))
+			defer pendo.Close()
+			tracker := &telemetry.Tracker{Clients: []telemetry.Client{&telemetry.PendoClient{Endpoint: pendo.URL, UserID: "fixture"}}}
+			rec := &gqlOpRecorder{}
+			api := rec.server(t, map[string]string{
+				"ResolveAppByName":                  resolveAppByNameBody,
+				"GetEnvironmentVariablesWithValues": envVarsWithValuesBody,
+			})
+			defer api.Close()
+			t.Setenv("API_HOST", api.URL)
+			k := newBootstrapKeychain(&bootstrapBackend{})
+			if mode != "login" {
+				if err := auth.NewStore(k).Save(raw); err != nil {
+					t.Fatal(err)
+				}
+			}
+			variable := "HELP"
+			if mode == "bypassed" {
+				variable = "help"
+			}
+			err := runWithDeps([]string{"config", "envvar", "get", variable, "--app", "example", "--env", "develop"}, runDeps{
+				Tracker:     tracker,
+				NewKeychain: func(string) *keychain.Keychain { return k },
+				NewLogin: func(store *auth.Store) func() (*auth.Token, error) {
+					return func() (*auth.Token, error) {
+						// Login events before saving a token must not issue anonymous requests.
+						tracker.TrackEvent("login_command_execute", nil)
+						if err := store.Save(raw); err != nil {
+							return nil, err
+						}
+						tracker.AliasUser(10000)
+						return parsedBootstrapToken(t, raw), nil
+					}
+				},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if rejected != 0 || accepted < 2 {
+				t.Fatalf("Pendo accepted=%d rejected=%d; expected authenticated command events only", accepted, rejected)
+			}
+		})
+	}
+}
+
+func TestPendoDebugFlagReachesClient(t *testing.T) {
+	for _, name := range []string{"DO_NOT_TRACK", "GO_ENV", "NODE_ENV", "DEBUG"} {
+		t.Setenv(name, "")
+	}
+	var out, diagnostics bytes.Buffer
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(401) }))
+	defer srv.Close()
+	tr := &telemetry.Tracker{Clients: []telemetry.Client{&telemetry.PendoClient{Endpoint: srv.URL, HTTP: srv.Client(), GetToken: func() (string, error) { return "private-token", nil }}}}
+	root := newRootBase(&rootContext{tracker: tr})
+	root.SetOut(&out)
+	root.SetErr(&diagnostics)
+	root.AddCommand(&cobra.Command{Use: "probe", Run: func(cmd *cobra.Command, _ []string) {
+		tr.TrackEvent("test", nil)
+		fmt.Fprintln(cmd.OutOrStdout(), "ok")
+	}})
+	root.SetArgs([]string{"probe", "-d"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if out.String() != "ok\n" || !strings.Contains(diagnostics.String(), "401") || strings.Contains(diagnostics.String(), "private-token") {
+		t.Fatalf("stdout=%q stderr=%q", out.String(), diagnostics.String())
+	}
+}
+
+func TestPendoImplicitLoginUsesDebugEnvironment(t *testing.T) {
+	for _, name := range []string{"DO_NOT_TRACK", "GO_ENV", "NODE_ENV", "VIP_TOKEN_OVERRIDE", "WPVIP_DEPLOY_TOKEN"} {
+		t.Setenv(name, "")
+	}
+	t.Setenv("DEBUG", "@automattic/vip:analytics:clients:pendo")
+	// Like Node, DEBUG is available during bootstrap, before command flag parsing.
+	output, err := os.CreateTemp(t.TempDir(), "stderr")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer output.Close()
+	previous := os.Stderr
+	os.Stderr = output
+	defer func() { os.Stderr = previous }()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(401) }))
+	defer srv.Close()
+	tr := &telemetry.Tracker{Clients: []telemetry.Client{&telemetry.PendoClient{Endpoint: srv.URL, HTTP: srv.Client()}}}
+	k := newBootstrapKeychain(&bootstrapBackend{})
+	err = runWithDeps([]string{"whoami"}, runDeps{
+		Tracker: tr, NewKeychain: func(string) *keychain.Keychain { return k },
+		NewLogin: func(store *auth.Store) func() (*auth.Token, error) {
+			return func() (*auth.Token, error) {
+				if err := store.Save("private-token"); err != nil {
+					return nil, err
+				}
+				tr.TrackEvent("login_command_token_submit_success", nil)
+				return nil, auth.ErrLoginCancelled // stop before any command API requests
+			}
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := output.Seek(0, 0); err != nil {
+		t.Fatal(err)
+	}
+	diagnostics, err := io.ReadAll(output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(diagnostics), "401") || strings.Contains(string(diagnostics), "private-token") {
+		t.Fatalf("bootstrap diagnostics=%q", diagnostics)
+	}
+}

package/cmd/vip-next/root.go

@@ -1,17 +1,22 @@
 package main
 
 import (
+	"context"
 	"errors"
+	"os"
 
 	"github.com/spf13/cobra"
 
 	"github.com/Automattic/vip/cmd/vip-next/commands"
 	"github.com/Automattic/vip/internal/appctx"
+	"github.com/Automattic/vip/internal/debuglog"
+	"github.com/Automattic/vip/internal/telemetry"
 	"github.com/Automattic/vip/internal/update"
 	"github.com/Automattic/vip/internal/version"
 )
 
 type rootContext struct {
+	tracker      *telemetry.Tracker
 	updateRunner commands.UpdateRunner
 	aliasApp     string
 	aliasEnv     string
@@ -43,6 +48,18 @@ func newRootBase(rc *rootContext) *cobra.Command {
 	root.PersistentFlags().Bool("non-interactive", false, "disable prompts; fail fast if a required flag is missing")
 
 	root.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
+		namespaces := os.Getenv("DEBUG")
+		if cmd.Flags().Changed("debug") {
+			if value, _ := cmd.Flags().GetString("debug"); value != "" {
+				namespaces = value
+			}
+		}
+		ctx := cmd.Context()
+		if ctx == nil {
+			ctx = context.Background()
+		}
+		cmd.SetContext(debuglog.WithLogger(ctx, namespaces, cmd.ErrOrStderr()))
+		rc.tracker.SetContext(cmd.Context())
 		flagApp, _ := cmd.Flags().GetString("app")
 		flagEnv, _ := cmd.Flags().GetString("env")
 		hasAlias := rc.aliasApp != "" || rc.aliasEnv != ""

package/dist/bin/vip-dev-env-envvar-get.js

@@ -15,7 +15,7 @@ const examples = [{
   usage: `${exampleUsage} MY_VARIABLE`,
   description: 'Retrieve the value of the local environment variable "MY_VARIABLE".'
 }];
-async function getEnvVarsCommand(args, opt) {
+async function getEnvVarCommand(args, opt) {
   (0, _logging.debug)('args: %o, opt: %o', args, opt);
   const slug = await (0, _devEnvironmentCli.getEnvironmentName)(opt);
   const trackingInfo = (0, _devEnvironmentCli.getEnvTrackingInfo)(slug);
@@ -41,4 +41,4 @@ async function getEnvVarsCommand(args, opt) {
 (0, _command.default)({
   requiredArgs: 1,
   usage
-}).option('slug', 'A unique name for a local environment. Default is "vip-local".', undefined, _devEnvironmentCli.processSlug).examples(examples).argv(process.argv, getEnvVarsCommand);
+}).option('slug', 'A unique name for a local environment. Default is "vip-local".', undefined, _devEnvironmentCli.processSlug).examples(examples).argv(process.argv, getEnvVarCommand);

package/dist/bin/vip-dev-env-envvar-set.js

@@ -24,7 +24,7 @@ const examples = [{
   usage: `${exampleUsage} MULTILINE_ENV_VAR --from-file=envvar-value.txt`,
   description: 'Add or update the local environment variable "MULTILINE_ENV_VAR" and assign the multiline contents of local file envvar-value.txt as its value.'
 }];
-async function deleteEnvVarCommand(args, opt) {
+async function setEnvVarCommand(args, opt) {
   (0, _logging.debug)('args: %o, opt: %o', args, opt);
   const slug = await (0, _devEnvironmentCli.getEnvironmentName)(opt);
   const trackingInfo = (0, _devEnvironmentCli.getEnvTrackingInfo)(slug);
@@ -76,4 +76,4 @@ async function deleteEnvVarCommand(args, opt) {
   requiredArgs: 1,
   wildcardCommand: true,
   usage
-}).option('slug', 'A unique name for a local environment. Default is "vip-local".', undefined, _devEnvironmentCli.processSlug).option('from-file', 'Read environment variable value from a UTF-8-encoded text file (useful for multiline input). Accepts a relative or absolute path.').examples(examples).argv(process.argv, deleteEnvVarCommand);
+}).option('slug', 'A unique name for a local environment. Default is "vip-local".', undefined, _devEnvironmentCli.processSlug).option('from-file', 'Read environment variable value from a UTF-8-encoded text file (useful for multiline input). Accepts a relative or absolute path.').examples(examples).argv(process.argv, setEnvVarCommand);

package/dist/bin/vip-dev-env-update.js

@@ -61,7 +61,7 @@ cmd.argv(process.argv, async (arg, opt) => {
       muPlugins: currentInstanceData.muPlugins.dir || currentInstanceData.muPlugins.tag || 'demo',
       wordpress: currentInstanceData.wordpress.tag || 'trunk',
       elasticsearch: currentInstanceData.elasticsearch,
-      php: currentInstanceData.php || _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS[Object.keys(_devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS)[0]].image,
+      php: currentInstanceData.php || _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS[_devEnvironment.DEV_ENVIRONMENT_DEFAULT_PHP_VERSION].image,
       mariadb: currentInstanceData.mariadb,
       phpmyadmin: currentInstanceData.phpmyadmin,
       xdebug: currentInstanceData.xdebug,

package/dist/lib/analytics/clients/pendo.js

@@ -4,6 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _debug = _interopRequireDefault(require("debug"));
 var _http = _interopRequireDefault(require("../../../lib/api/http"));
+var _token = _interopRequireDefault(require("../../token"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const debug = (0, _debug.default)('@automattic/vip:analytics:clients:pendo');
 /**
@@ -27,7 +28,7 @@ class Pendo {
     if (!eventName.startsWith(this.eventPrefix)) {
       eventName = this.eventPrefix + eventName;
     }
-    debug('trackEvent()', eventProps);
+    debug('trackEvent()');
     this.context = {
       ...this.context,
       org_id: eventProps.org_slug,
@@ -38,12 +39,17 @@ class Pendo {
     };
     try {
       return await this.send(eventName, eventProps);
-    } catch (error) {
-      debug(error);
-      return Promise.resolve(false);
+    } catch {
+      debug('Pendo event delivery failed');
+      return false;
     }
   }
   async send(eventName, eventProps) {
+    const token = await _token.default.get();
+    if (!token.raw) {
+      debug('Skipping Pendo event: authentication token unavailable');
+      throw new Error('Pendo authentication token unavailable');
+    }
     const body = {
       context: this.context,
       event: eventName,
@@ -53,13 +59,19 @@ class Pendo {
       visitorId: `${this.context.userId}`,
       accountId: `${this.context.org_sfid}`
     };
-    debug('send()', body);
+    debug('send()');
     const response = await (0, _http.default)(Pendo.ENDPOINT, {
       method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token.raw}`
+      },
       body: JSON.stringify(body)
     });
-    const responseText = await response.text();
-    debug('response', responseText);
+    await response.text();
+    debug('Pendo response status=%d', response.status);
+    if (!response.ok) {
+      throw new Error(`Pendo request failed with HTTP ${response.status}`);
+    }
     return response;
   }
 }

package/dist/lib/constants/dev-environment.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.DEV_ENVIRONMENT_WORDPRESS_VERSION_TTL = exports.DEV_ENVIRONMENT_WORDPRESS_VERSIONS_URI = exports.DEV_ENVIRONMENT_WORDPRESS_CACHE_KEY = exports.DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_SUBCOMMAND = exports.DEV_ENVIRONMENT_RAW_GITHUB_HOST = exports.DEV_ENVIRONMENT_PROMPT_INTRO = exports.DEV_ENVIRONMENT_PHP_VERSIONS = exports.DEV_ENVIRONMENT_NOT_FOUND = exports.DEV_ENVIRONMENT_FULL_COMMAND = exports.DEV_ENVIRONMENT_DEFAULTS = exports.DEV_ENVIRONMENT_COMPONENTS_WITH_WP = exports.DEV_ENVIRONMENT_COMPONENTS = void 0;
+exports.DEV_ENVIRONMENT_WORDPRESS_VERSION_TTL = exports.DEV_ENVIRONMENT_WORDPRESS_VERSIONS_URI = exports.DEV_ENVIRONMENT_WORDPRESS_CACHE_KEY = exports.DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_SUBCOMMAND = exports.DEV_ENVIRONMENT_RAW_GITHUB_HOST = exports.DEV_ENVIRONMENT_PROMPT_INTRO = exports.DEV_ENVIRONMENT_PHP_VERSIONS = exports.DEV_ENVIRONMENT_NOT_FOUND = exports.DEV_ENVIRONMENT_FULL_COMMAND = exports.DEV_ENVIRONMENT_DEFAULT_PHP_VERSION = exports.DEV_ENVIRONMENT_DEFAULTS = exports.DEV_ENVIRONMENT_COMPONENTS_WITH_WP = exports.DEV_ENVIRONMENT_COMPONENTS = void 0;
 const DEV_ENVIRONMENT_SUBCOMMAND = exports.DEV_ENVIRONMENT_SUBCOMMAND = 'dev-env';
 const DEV_ENVIRONMENT_FULL_COMMAND = exports.DEV_ENVIRONMENT_FULL_COMMAND = `vip ${DEV_ENVIRONMENT_SUBCOMMAND}`;
 const DEV_ENVIRONMENT_PROMPT_INTRO = exports.DEV_ENVIRONMENT_PROMPT_INTRO = 'This is a wizard to help you set up your local dev environment.\n\n' + 'Sensible default values were pre-selected for convenience. ' + 'You may also choose to create multiple environments with different settings using the --slug option.\n\n';
@@ -14,26 +14,27 @@ const DEV_ENVIRONMENT_WORDPRESS_CACHE_KEY = exports.DEV_ENVIRONMENT_WORDPRESS_CA
 const DEV_ENVIRONMENT_WORDPRESS_VERSION_TTL = exports.DEV_ENVIRONMENT_WORDPRESS_VERSION_TTL = 86400; // once per day
 
 const DEV_ENVIRONMENT_PHP_VERSIONS = exports.DEV_ENVIRONMENT_PHP_VERSIONS = {
-  8.2: {
+  '8.2': {
     image: 'ghcr.io/automattic/vip-container-images/php-fpm:8.2',
-    label: '8.2 (recommended)'
+    label: '8.2'
   },
-  8.3: {
+  '8.3': {
     image: 'ghcr.io/automattic/vip-container-images/php-fpm:8.3',
     label: '8.3'
   },
-  8.4: {
+  '8.4': {
     image: 'ghcr.io/automattic/vip-container-images/php-fpm:8.4',
     label: '8.4'
   },
-  8.5: {
+  '8.5': {
     image: 'ghcr.io/automattic/vip-container-images/php-fpm:8.5',
     label: '8.5 (experimental)'
   }
 };
+const DEV_ENVIRONMENT_DEFAULT_PHP_VERSION = exports.DEV_ENVIRONMENT_DEFAULT_PHP_VERSION = '8.4';
 const DEV_ENVIRONMENT_DEFAULTS = exports.DEV_ENVIRONMENT_DEFAULTS = {
   title: 'VIP Dev',
   multisite: false,
-  phpVersion: Object.keys(DEV_ENVIRONMENT_PHP_VERSIONS)[0]
+  phpVersion: DEV_ENVIRONMENT_DEFAULT_PHP_VERSION
 };
 const DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_VERSION = '2.3.4';

package/dist/lib/dev-environment/dev-environment-cli.js

@@ -524,7 +524,7 @@ function resolvePhpVersion(version) {
   }
   debug(`Resolving PHP version %j`, version);
   let result;
-  if (!(version in _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS)) {
+  if (!Object.hasOwn(_devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS, version)) {
     const images = Object.values(_devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS);
     const image = images.find(value => value.image === version);
     if (image) {
@@ -545,8 +545,9 @@ async function promptForPhpVersion(initialValue) {
     const choices = [];
     Object.keys(_devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS).forEach(version => {
       const phpImage = _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS[version];
+      const label = version === _devEnvironment.DEV_ENVIRONMENT_DEFAULT_PHP_VERSION ? `${phpImage.label} (recommended)` : phpImage.label;
       choices.push({
-        message: phpImage.label,
+        message: label,
         value: version
       });
     });
@@ -744,19 +745,29 @@ async function getTagChoices() {
     };
   });
 }
+
+// Keep this list in sync with vip-next's devEnvTrackingInfo. Instance data may
+// contain credentials and user-defined fields that must stay local (PLTFRM-2820).
+const TRACKING_ALLOWED_KEYS = ['siteSlug', 'wpTitle', 'multisite', 'wordpress', 'muPlugins', 'appCode', 'mediaRedirectDomain', 'phpmyadmin', 'xdebug', 'xdebugConfig', 'mariadb', 'php', 'elasticsearch', 'mailpit', 'photon', 'cron', 'pullAfter', 'version'];
 function getEnvTrackingInfo(slug) {
   try {
     const envData = (0, _devEnvironmentCore.readEnvironmentData)(slug);
     const result = {
       slug
     };
-    for (const key of Object.keys(envData)) {
+    for (const key of TRACKING_ALLOWED_KEYS) {
+      if (!Object.hasOwn(envData, key)) {
+        continue;
+      }
+
       // track doesn't like camelCase
       const snakeCasedKey = key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
       const value = _devEnvironment.DEV_ENVIRONMENT_COMPONENTS_WITH_WP.includes(key) ? JSON.stringify(envData[key]) : envData[key];
       result[snakeCasedKey] = value;
     }
-    result.php = result.php.replace(/^[^:]+:/, '');
+    if (typeof result.php === 'string') {
+      result.php = result.php.replace(/^[^:]+:/, '');
+    }
     return result;
   } catch {
     return {

package/dist/lib/dev-environment/dev-environment-core.js

@@ -164,7 +164,7 @@ function preProcessInstanceData(instanceData) {
     mariadb: instanceData.mariadb ?? '',
     elasticsearch: instanceData.elasticsearch || false,
     // NOSONAR
-    php: instanceData.php ?? _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS[Object.keys(_devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS)[0]].image,
+    php: instanceData.php ?? _devEnvironment.DEV_ENVIRONMENT_PHP_VERSIONS[_devEnvironment.DEV_ENVIRONMENT_DEFAULT_PHP_VERSION].image,
     xdebug: Boolean(instanceData.xdebug),
     phpmyadmin: Boolean(instanceData.phpmyadmin),
     photon: Boolean(instanceData.photon),

package/docs/BUILD-SIGNING.md

@@ -229,7 +229,7 @@ real release with a CA certificate.
 Release builds run on **Buildkite** (Automattic's signing stack), not GitHub
 Actions. See `.buildkite/pipeline.yml` and the per-platform scripts.
 
-- **Pipeline:** `.buildkite/pipeline.yml` — three independent steps (macOS,
+- **Pipeline:** `.buildkite/pipeline.yml` — three independent binary steps (macOS,
   Windows, Linux), each building on its own native agent.
   Setup sources `.buildkite/shared-pipeline-vars` before pipeline upload
   (CI toolkit plugin pin, `BIN_BASE`, `IMAGE_ID`).
@@ -240,13 +240,151 @@ Actions. See `.buildkite/pipeline.yml` and the per-platform scripts.
   every build.
 - **macOS certs:** fastlane `match` (`fastlane/Fastfile` →
   `configure_code_signing`), `type: developer_id`, stored in S3
-  (`a8c-fastlane-match`). Signing and notarization are the
-  `sign_and_notarize` lane: Developer ID Application, identifier
-  `com.automattic.vip-cli`, no staple on a bare Mach-O.
+  (`a8c-fastlane-match`), in readonly mode. The separate
+  `configure_installer_signing` lane adds the Developer ID Installer
+  certificate through match's `additional_cert_types`. Signing and
+  notarization are the `sign_and_notarize` lane: Developer ID Application,
+  identifier `com.automattic.vip-cli`, no staple on a bare Mach-O.
 - **macOS artifacts:** per-arch `.tar.gz` of `vip-next` + `go-search-replace`,
-  both signed and notarized (online-verified).
+  both signed and notarized (online-verified), plus a signed, notarized,
+  stapled `.pkg` for each architecture.
 - **Windows / Linux artifacts:** the same tarball layout. Windows Authenticode-
-  signs both PEs via Azure Trusted Signing; Linux checksums only.
+  signs both PEs and the x64 `.msi` via Azure Trusted Signing; Linux checksums only.
+
+### Native installers
+
+Separate macOS and Windows installer jobs depend on their platform's binary
+job. They download its signed archives from the same Buildkite build, verify
+checksums and the exact two-file payload, and package those existing bytes.
+Installer jobs use Buildkite `soft_fail` so missing signing prerequisites or
+packaging failures do not fail the binary build. Their failures remain visible
+in Buildkite. Archives remain available for portable installations and
+`vip-next update`. No Node.js runtime is installed or required by these packages.
+
+| Platform            | Package                      | Installation                        |
+| ------------------- | ---------------------------- | ----------------------------------- |
+| macOS Apple Silicon | `vip-next-darwin-arm64.pkg`  | `/usr/local/lib/vip-cli/bin`        |
+| macOS Intel         | `vip-next-darwin-amd64.pkg`  | `/usr/local/lib/vip-cli/bin`        |
+| Windows x64         | `vip-next-windows-amd64.msi` | `%ProgramFiles%\Automattic\VIP CLI` |
+
+Run the package to install or upgrade; administrative privileges are required.
+Open a new terminal afterward, then run `vip-next --version`. The macOS package
+adds `/etc/paths.d/vip-cli`; Windows adds its directory to the system PATH and
+removes that entry on uninstall. Neither package creates a `vip` alias or
+replaces the Node/npm installation. Existing earlier PATH entries can still
+select a different `vip-next`; use `command -v vip-next` (macOS) or
+`where.exe vip-next` (Windows) to identify the active installation.
+
+Installer-owned directories contain `.vip-next-installer.json`. The Go updater
+recognizes this file and directs users to download the appropriate installer
+instead of replacing package-managed binaries. Keep this metadata intact.
+`vip-next update --check` still checks for available releases. Portable tarballs
+do not contain this marker and retain their existing self-update behavior.
+
+On Windows, uninstall **VIP CLI** through Installed apps or `msiexec /x` with
+the installed package. On macOS, run:
+
+```sh
+sudo /usr/local/lib/vip-cli/uninstall.sh
+```
+
+The macOS uninstaller removes only package-owned files, the matching PATH entry,
+and its receipt (`com.automattic.vip-cli`); it preserves other files in the
+installation directory. Neither uninstaller deletes user configuration or
+credentials. Uninstall first if deliberately moving to an older version.
+
+#### Build prerequisites
+
+- **macOS:** `configure_code_signing` retrieves only the **Developer ID Application**
+  certificate. The installer job separately calls `configure_installer_signing`
+  for the **Developer ID Installer** certificate. Both use the existing fastlane
+  match S3 storage in readonly mode. Builds never create or renew certificates.
+  The Installer certificate is not yet in match storage, so the installer job
+  fails until it is provisioned (see below). Xcode command-line tools provide
+  `pkgbuild`, `productbuild`, `productsign`, `notarytool`, and `stapler`.
+- **Windows:** the build uses .NET SDK 8 and pinned WiX 5.0.2, with a matching
+  UI extension, as build-only tools. WiX is restored into a temporary build
+  directory. This pin does not adopt WiX 6+ sponsorship requirements. Existing
+  Azure Trusted Signing credentials/signing tools sign the final MSI.
+- Missing signing prerequisites fail only the corresponding job; there is no
+  unsigned fallback. Binary job failures still fail the build. Installer jobs
+  upload explicitly only after all packages pass signing and payload verification;
+  automatic post-failure uploads are disabled. Checksums follow final signing/stapling.
+
+The promotion helper requires all five archive/checksum pairs (10 assets).
+The three installer/checksum pairs are optional (up to 16 assets total), but a
+package and its checksum must appear together. It verifies every supplied
+checksum, the exact two-binary tar layout, and the installer container type.
+Unknown, duplicate, incomplete, or corrupt artifacts still block promotion. Native jobs verify
+signatures; the Linux promotion job does not independently verify Apple or
+Authenticode signatures. Before checksumming/uploading, macOS expands the final
+PKG and Windows performs a temporary administrative extraction of the signed
+MSI to verify the packaged executable hashes, license, and ownership metadata.
+These checks do not install the CLI on the Buildkite host.
+
+#### Provisioning the Developer ID Installer certificate
+
+App Store Connect's API does not model this certificate type at all:
+`filter[certificateType]=DEVELOPER_ID_INSTALLER` is rejected as an invalid
+value, and the accepted list contains `DEVELOPER_ID_APPLICATION` and
+`DEVELOPER_ID_KEXT` but no installer entry. No API-driven inventory can
+therefore report whether the team already holds one; check
+<https://developer.apple.com/account/resources/certificates> directly. Creating
+one is Account Holder only and cannot be automated from CI.
+
+Import the `.cer` and `.p12` into match storage (the command prompts for both
+paths):
+
+```sh
+bundle exec fastlane match import \
+  --type developer_id_installer \
+  --platform macos \
+  --team_id PZYM8XX95Q \
+  --storage_mode s3 \
+  --s3_bucket a8c-fastlane-match \
+  --s3_region us-east-2 \
+  --skip_provisioning_profiles true \
+  --skip_certificate_matching true
+```
+
+`--skip_certificate_matching true` is required, not optional: without it
+`match import` looks the certificate up on the portal by type to recover its
+ID, which fails on the same rejected filter value.
+
+Note the asymmetry: `match import` handles `developer_id_installer` as a
+top-level `--type`, but `match` itself does not. Fetching it requires
+`additional_cert_types`, as `configure_installer_signing` does — passing it as
+match's top-level `type` silently installs an Apple Distribution certificate
+instead and reports success.
+
+#### Package version ordering
+
+MSI requires three numeric version fields. Both installer formats use
+`major.minor.(patch * 1000 + stage)` from `cmd/installer-version`: development
+builds use stage 0; alpha.N uses 100+N; beta.N uses 300+N; rc.N uses 500+N;
+stable uses 999. For example, `5.0.0-beta.1` becomes `5.0.301` and `5.0.0`
+becomes `5.0.999`. The binaries retain their full semantic version.
+
+Major/minor are limited to 255, patch to 64, and prerelease sequence to 199.
+Unsupported values fail explicitly in installer jobs; binary releases retain
+their existing semantic-version range.
+Development builds of the same semantic base share a package version and may
+require uninstalling the previous development MSI before installing another.
+
+#### Installer tests
+
+`python3 -m unittest discover -s packaging/macos -p 'test_package.py'` creates
+and expands real unsigned packages in temporary directories. It verifies
+payload bytes and runs preinstall conflict/downgrade checks against a temporary
+volume tree; it does not install on the host.
+
+The existing Go CI native matrix also runs `packaging/macos/test-install.sh`
+and `packaging/windows/test-msi.ps1` on disposable GitHub-hosted runners. These
+tests require `VIP_INSTALLER_E2E=1`, check for pre-existing installations, and
+exercise actual install, upgrade, downgrade refusal, executable versions, PATH,
+updater ownership, and uninstall using unsigned fixture packages. They are not
+run on shared Buildkite agents. Signature/notarization validation happens in
+the production Buildkite build and must also pass before a release is promoted.
 
 ### GitHub prerelease promotion setup
 
@@ -282,6 +420,9 @@ On a Buildkite build, confirm:
 - macOS binaries: `codesign --verify --strict --verbose=2` passes and
   `codesign --display` shows `Identifier=com.automattic.vip-cli`.
 - Windows: `signtool verify /pa /v <exe>` passes.
+- macOS installers: `pkgutil --check-signature <pkg>`, `xcrun stapler validate
+<pkg>`, and `spctl --assess --type install <pkg>` pass.
+- Windows installer: `signtool verify /pa /v <msi>` passes.
 - Every artifact has a matching `.sha256`.
 
 ## Release checklist

package/docs/DEBUGGING.md

@@ -31,3 +31,64 @@ For help, see: https://nodejs.org/en/docs/inspector
 6. Confirm that you attached the debugger to continue command execution.
 7. Resolve the problem.
 8. [Optional but recommended] Pay it forward and implement a similar approach to other internal/external tooling.
+
+## Go CLI diagnostics
+
+Use `-d` or `--debug` to send diagnostics to stderr while keeping command results on stdout:
+
+```sh
+vip-next dev-env list --debug
+vip-next @example.develop edge-workers list -d --format=json > workers.json
+```
+
+The Go CLI uses the corresponding Node CLI namespaces. Select namespaces with a
+comma-separated list or wildcards, and exclude namespaces with a leading `-`:
+
+```sh
+vip-next @example.develop edge-workers list --debug='@automattic/vip:http*'
+vip-next dev-env list --debug='*,-vip:proxy-dispatcher'
+DEBUG='@automattic/vip:bin:dev-environment' vip-next dev-env list
+```
+
+A nonempty debug flag overrides `DEBUG`. For remote WP-CLI, put VIP's debug flag **before**
+`wp`; arguments after `wp` belong to WP-CLI:
+
+```sh
+vip-next @example.develop -d wp option get home
+```
+
+### Available diagnostics
+
+| Namespace                                                                                  | Diagnostics                                                                                                   |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `@automattic/vip:http`                                                                     | API requests, without URL credentials or arbitrary query parameters                                           |
+| `@automattic/vip:http:graphql`                                                             | Failed requests, retries, operation names, HTTP status, safe GraphQL error metadata                           |
+| `vip:proxy-dispatcher`                                                                     | Selected proxy scheme and host                                                                                |
+| `@automattic/vip:analytics:clients:pendo`                                                  | Telemetry send/skip stages and HTTP response status, without credentials, event properties or response bodies |
+| `@automattic/vip:rechallenge:*`                                                            | Step-up session creation, pending polling, flow failures                                                      |
+| `@automattic/vip:bin:dev-environment`                                                      | Local environment lifecycle, discovered environments, container status, import and execution stages           |
+| `@automattic/vip:bin:config:envvar`                                                        | Remote and local environment-variable operations, without values                                              |
+| `@automattic/vip:bin:config-software`                                                      | Software update requests and polling                                                                          |
+| `@automattic/vip:bin:vip-app-deploy*`                                                      | Deployment validation and upload/deployment stages                                                            |
+| `@automattic/vip:bin:vip-import-sql`, `vip:vip-import-sql`, `vip:validations:line-by-line` | SQL import options and validation summaries                                                                   |
+| `vip:vip-import-media`                                                                     | Media import summaries                                                                                        |
+| `vip:lib/client-file-uploader`                                                             | Compression, checksum computation, upload strategy and completion                                             |
+| `vip:lib/site-import/status`                                                               | SQL import job and step status                                                                                |
+| `@automattic/vip:lib:search-and-replace`                                                   | Input/output routing and processing stages                                                                    |
+| `@automattic/vip:wp`, `@automattic/vip:wp/ssh`                                             | Remote connection, retry and exit stages                                                                      |
+
+Messages follow each runtime's implementation. Go uses Compose rather than Lando,
+so Lando initialization messages do not apply. Raw argument, configuration,
+response, SQL and credential dumps from older Node diagnostics are replaced with
+targeted summaries. A successful command can remain quiet when its implementation
+has no applicable diagnostics, or when its namespaces are excluded.
+
+The command-family audit covered app, backup, cache, config, db, defensive-mode,
+dev-env, edge-workers, export, import, login, logout, logs, search-replace,
+slowlogs, sync, update, whoami and wp. Families without command-specific Node
+diagnostics use shared request logging where applicable. The Go-only updater has
+no Node command diagnostics to port. Use `DEBUG` to inspect Pendo delivery during
+authentication bootstrap, before command flags are parsed. Pendo requests use the
+current stored token and are skipped when no token is available. Delivery failures
+do not fail the command. Tracking opt-outs also disable Pendo; these diagnostics
+do not add credential-store dumps.

package/docs/GO-UPDATES.md

@@ -86,6 +86,12 @@ beside the CLI. PATH and `VIP_SEARCH_REPLACE_BIN` targets are never overwritten;
 an active override continues to control helper execution.
 
 Recognized package-managed installations receive package-manager instructions
-instead of file replacement. Missing bundles, ambiguous layouts, and unwritable
+instead of file replacement. Installations created by the macOS `.pkg` or
+Windows `.msi` contain `.vip-next-installer.json` beside the binaries; keep this
+file intact. When an update is available, `vip-next update` directs these
+installations to the matching installer download. `--check` remains available.
+See [native installer installation and upgrades](BUILD-SIGNING.md#native-installers).
+
+Missing bundles, ambiguous layouts, and unwritable
 locations require manual installation. The updater does not elevate privileges.
 Supported release assets are macOS and Linux amd64/arm64, and Windows amd64.