feat(v8): foundation for the major 8.0 release (#5128)

* chore(release): adopt Lerna 5 with GitHub Releases and add v8 breaking-change docs

- Bump root lerna devDependency 3.13.3 -> 5.6.2 (matches ionic-framework)
- publish:ci passes --create-release github so Lerna creates a GitHub Release
  per published tag; cd.yml provides GH_TOKEN (built-in token, contents: write)
- Add BREAKING.md (+ BREAKING_ARCHIVE/ convention) seeding the v8 removed-command log
- Add .github/RELEASING.md major-release runbook

* fix(cli): make build, lint, and tests run on Windows and macOS

Pre-existing cross-platform issues surfaced while validating the Lerna 5
upgrade; none are caused by the release tooling:

- discover: pin netmask 2.0.2 and @types/netmask 2.0.5 — the untracked
  dependency tree had drifted to netmask 2.1.x, whose bundled types declare
  'broadcast: string | undefined' and broke the build (TS2322)
- replace the Unix-only 'lint': 'true' no-op with cross-platform 'exit 0' in
  all packages ('true' is not a cmd.exe builtin, so npm run lint failed on Windows)
- angular/cordova tests: normalize path separators in assertions and return the
  floating expect().resolves promises (fixes Windows path failures and the
  resulting jest-worker 'Call retries were exceeded' crash)

* docs(release): correct publish:testing guidance in runbook

publish:testing is NOT a dry run — lerna publish runs npm publish (testing
dist-tag); --no-push only suppresses git. It also only runs from 'stable' due
to the allowBranch guard. Replace the §4 'dry run' step with a safe,
non-publishing 'lerna version --no-push --no-git-tag-version --allow-branch'
smoke test, and document the bump-from-commits behavior.

* ci: pin actions to commit SHAs and bump to latest

Security-harden workflows by pinning actions to immutable commit SHAs
(version in trailing comment), and update from v3:

- actions/checkout  v3 -> v6.0.3
- actions/setup-node v3 -> v6.4.0
- actions/cache      v3 -> v5.0.5 (v3 cache backend was retired by GitHub)

* chore(deps): upgrade to TypeScript 5.9.3 and jest 29

Upgrade the TypeScript toolchain across all packages:

- typescript    ~4.8.0  -> ~5.9.3
- ts-jest       ~26.3.0 -> ^29.4.11
- jest/jest-cli ^26.x   -> ^29.7.0  (stays on 29 to keep Node 16 support)
- @types/jest   ^26.x   -> ^29.5.14
- @types/node   ~16.0.0 -> ^16.18.126 (16.0.3 conflicted with TS 5.9 libs)
- tslib         ^2.0.1  -> ^2.8.1

Required code/config changes:
- jest.config.base.js: migrate ts-jest globals -> transform API, tsConfig -> tsconfig, explicit testEnvironment: node
- utils-array reduce(): annotate accumulator T|U + cast awaited result (TS 5.9 Awaited/NonNullable inference)
- tests: drop async from async-done callbacks (utils-fs), convert to async()+expect.assertions (utils-subprocess), spyOn().and.callFake -> jest.spyOn().mockImplementation (utils-network), legacyFakeTimers for timer-mock assertions (cli-framework-output)

Validated: build + lint + full test suite green.

* docs(release): make the runbook smoke-test command cross-shell

The step-4 lerna version command used a bash-only backslash continuation and
$(git branch --show-current), which fail in PowerShell/cmd. Use a single-line
command with --allow-branch "*" (quoted so bash doesn't glob-expand it) so it
runs identically in PowerShell, cmd, bash, and zsh. Also scope the cleanup to
'git checkout -- packages' so it only discards lerna's version writes.

* Update .github/RELEASING.md

Co-authored-by: Shane <shane@shanessite.net>

* fix(discover): let netmask float and handle nullable broadcast

netmask was pinned to an exact 2.0.2 to dodge a TS2322 build break. The
break originates from netmask >= 2.1, which ships its own bundled type
declarations (broadcast: string | undefined) that shadow @types/netmask
entirely — so pinning @types/netmask alone does not fix it.

Instead, restore the caret (^2.0.2) so the runtime can receive 2.x
patches, drop the now-shadowed @types/netmask dev dependency, and handle
the nullable broadcast in computeBroadcastAddress (broadcast is absent
for /31 and /32 blocks; fall back to the network address).

Validated: discover build + tests green with netmask 2.1.1.

* docs(release): refresh Node guidance for the jest 29 toolchain

The pre-publish validation note referenced a "bundled jest 26 worker"
caveat that is stale on this branch (it ships jest 29). jest 29 supports
newer Node than 26 did, so drop the caveat and state the validated
matrix: Node 18 to match CI, with the suite also green on Node 16 and 24.

* ci: block publishing BREAKING.md with unfilled <TODO placeholders

The v8 BREAKING.md entries are seeded placeholders that each removal PR
fills in. Add a guard to the stable publish pipeline that fails if any
<TODO marker remains, so the "each removal PR fills it in" contract is
enforced rather than risking placeholders shipping to users at 8.0.0.

* docs: add pull request template

Mirror the Ionic Framework PR template so contributors get a consistent
structure: issue reference, current/new behavior, a breaking-change
checkbox with migration guidance, and an other-information section. The
breaking-change note points at this repo's BREAKING.md and the
Conventional Commits footer format used by the publish pipeline.

* Update .github/RELEASING.md

Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>

* Update .github/RELEASING.md

Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>

* feat!: require Node >= 18

Enforce the supported runtime through package.json rather than leaving it
to documentation. Set engines.node to ">=18.0.0" across the monorepo: the
root workspace, every published @ionic/* package, and the previously unset
@ionic/discover and cli-scripts manifests.

Align the rest of the toolchain with the new baseline — drop Node 16.x
from the CI matrix (now 18.x and 20.x) and update the release runbook so
the recommended and minimum Node versions no longer disagree.

BREAKING CHANGE: Node 16 is no longer supported. The Ionic CLI and its
@ionic/* packages now require Node 18 or newer.

* docs(release): correct the discover drift-guard note

The step-3 drift guard still described the old netmask@2.0.2 +
@types/netmask@2.0.5 pins. That approach was replaced: netmask floats at
^2.0.2 (resolving to 2.1.x) using its own bundled types, @types/netmask
was dropped, and computeBroadcastAddress handles the nullable broadcast.
Update the note to match.

* docs(release): point to source files for Node versions

Stop hardcoding specific Node versions in the runbook. Reference the
authoritative sources instead — `engines.node` in package.json for the
minimum and the `node:` matrix in ci.yml (plus `node-version` in cd.yml)
for the versions CI exercises — so the doc stays correct when CI's Node
versions change without a separate edit.

---------

Co-authored-by: Shane <shane@shanessite.net>
Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>

Author: 3 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+Issue number: resolves #
+
+---------
+
+<!-- Please do not submit updates to dependencies unless it fixes an issue. -->
+
+<!-- Please try to limit your pull request to one type (bugfix, feature, etc). Submit multiple pull requests if needed. -->
+
+## What is the current behavior?
+<!-- Please describe the current behavior that you are modifying. -->
+
+## What is the new behavior?
+<!-- Please describe the behavior or changes that are being added by this PR. -->
+
+-
+-
+-
+
+## Does this introduce a breaking change?
+
+- [ ] Yes
+- [ ] No
+
+<!--
+  If this introduces a breaking change:
+  1. Describe the impact and migration path for existing applications below.
+  2. Update the BREAKING.md file with the breaking change.
+  3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://www.conventionalcommits.org/ for more information.
+-->
+
+
+## Other information
+
+<!-- Any other information that is important to this PR such as screenshots of how the change behaves before and after. -->

.github/RELEASING.md

@@ -0,0 +1,164 @@
+# Releasing the Ionic CLI
+
+This runbook describes how the Ionic CLI is published and, specifically, **how
+to cut a major release** (e.g. `8.0.0`). It reflects the repository as of the
+`major-x` branch.
+
+## 1. How publishing works today
+
+The CLI is a **Lerna monorepo** with `independent` versioning
+([`lerna.json`](../lerna.json) → `"version": "independent"`). 
+Each `@ionic/*`
+package is versioned on its own based on the commits that touched it.
+
+Release is **conventional-commit driven and automatic**:
+
+- [`.github/workflows/cd.yml`](workflows/cd.yml) runs **only on push to the
+  `stable` branch**.
+- It runs `npm run publish:ci`, defined in [`package.json`](../package.json):
+
+  - `lerna version --conventional-commits` computes each package's next version
+    **from commit messages**, tags, and pushes the release commit.
+  - `--create-release github` makes Lerna create the **GitHub Release** for each
+    tag (see **3** — requires Lerna 5 and a `GH_TOKEN`).
+  - `lerna exec ... npm publish --provenance` publishes the changed packages to
+    npm.
+- `lerna.json` pins `"allowBranch": "stable"`, so `lerna version` refuses to run
+  from any other branch.
+- After publishing, `cd.yml` builds and pushes a Docker image to GHCR (GitHub Container Registry).
+
+> **Key consequence:** the version bump is derived from commit messages, **not**
+> from `BREAKING.md`. `BREAKING.md` is human documentation only. To land
+> `@ionic/cli` on `8.0.0`, the branch history must contain **breaking-change
+> commits** — a `feat!:` / `fix!:` subject or a `BREAKING CHANGE:` footer — for
+> the `@ionic/cli` package.
+
+## 2. Cutting the v8 major
+
+### 2a. Make sure the major bump will be computed
+
+Because versioning is conventional-commit driven:
+
+- The command-removal PRs (tracked separately) **must** use breaking-change
+  commit syntax so Lerna computes a major bump for the affected package(s):
+
+  ```bash
+  feat(commands)!: remove deprecated Appflow/Enterprise/Cordova commands
+
+  BREAKING CHANGE: The config, cordova, enterprise, git, init, link,
+  live-update, login, logout, repair, signup, and ssh commands have been
+  removed. See BREAKING.md.
+  ```
+
+- `independent` versioning means **only the packages whose commits include the
+  breaking change get the major bump**. Confirm the removals live in the package
+  that owns the command surface (typically `@ionic/cli`) so `@ionic/cli` is the
+  one that reaches `8.0.0`. Utility `@ionic/*` packages bump independently based
+  on their own commits.
+
+### 2b. Path to publish from `major-8.0`
+
+`cd.yml` only publishes from `stable`. The `major-8.0` work branch is **not**
+auto-published. Recommended path:
+
+1. Land all removal PRs (with breaking-change commits) onto `major-8.0`.
+2. Normal merge / rebase `major-8.0` → `develop`.
+3. Follow the normal `develop` → `stable` promotion. The push to `stable`
+   triggers `cd.yml`, which computes the major bump, tags, publishes to npm, and
+   creates the GitHub Releases.
+
+### 2c. Optional: ship a v8 release candidate first
+
+Use a prerelease on a `next` dist-tag before GA so consumers can test:
+
+```bash
+# A real prerelease under the `testing` dist-tag (publishes to npm, no git push):
+npm run publish:testing   # publishes a `testing` prerelease with --no-push
+
+# A real RC under the `next` tag (run from an allowed branch):
+lerna publish premajor --preid rc --dist-tag next --conventional-commits
+```
+
+> To cut an RC directly from `major-8.0`, temporarily relax `allowBranch` in
+> `lerna.json` (e.g. `["stable", "major-8.0"]`) or run the prerelease from
+> `stable`. Decide this deliberately — don't leave `major-8.0` permanently
+> publishable.
+
+## 3. GitHub Release creation (Lerna 5)
+
+The CLI was upgraded from Lerna **3.13.3 → 5.x** so that releases are created on
+GitHub natively. This is wired via
+`--create-release github` in `publish:ci` (**1**).
+
+Requirements for `--create-release github` to work in CI:
+
+- It must run together with `--conventional-commits` (it is).
+- A **`GH_TOKEN`** must be present in the environment of the `lerna version`
+  step. [`cd.yml`](workflows/cd.yml) provides it as `${{ github.token }}` — the
+  built-in workflow token, which is sufficient because the workflow already
+  grants `contents: write`. **No dedicated secret is required.**
+
+## 4. Pre-publish validation (always, but especially after the Lerna upgrade)
+
+These steps are **cross-platform** — every command is `npm`/`npx`-based and runs
+identically in PowerShell, `cmd`, bash, and zsh (Windows and macOS). For the Node
+version, don't rely on a number hardcoded here: the minimum is enforced by
+`engines.node` in each `package.json`, and the versions CI exercises are the
+`node:` matrix in [`ci.yml`](workflows/ci.yml) (the publish job pins its own under
+`node-version` in [`cd.yml`](workflows/cd.yml)). Use a version that satisfies both
+— checking those files keeps this runbook correct as the supported versions change.
+
+> **Order matters.** This is a `lerna bootstrap` monorepo: per-package
+> devDependencies (including `@types/node`) are installed and hoisted by
+> `npm run bootstrap`, **not** by `npm install`. You must run steps 0→1 before
+> any `build`/`lint`/`test`. Running `npm run build` on a freshly-cleaned tree
+> fails with `TS2688: Cannot find type definition file for 'node'` — that means
+> bootstrap was skipped, not a real code error.
+
+```bash
+# 0. (optional) Pristine tree — npx rimraf is cross-platform, unlike rm -rf
+npx rimraf node_modules "packages/@ionic/*/node_modules" "packages/cli-scripts/node_modules"
+
+# 1. Install + bootstrap — REQUIRED before build/lint/test.
+#    `npm install` only installs root devDeps (lerna, typescript);
+#    `npm run bootstrap` installs+hoists every package's deps, then builds.
+npm install
+npm run bootstrap
+
+# 2. Confirm the Lerna upgrade — expect 5.x, and `--create-release` in the help
+npx lerna --version
+npx lerna version --help        # look for: --create-release ... [choices: "gitlab","github"]
+
+# 3. Lint / test  (bootstrap already built; re-run build explicitly if you like)
+npm run lint
+npm run test
+#    Drift guard: a green build of @ionic/discover (no publisher.ts "broadcast"
+#    TS2322) confirms netmask (^2.0.2, currently 2.1.x) resolved with its
+#    bundled types and computeBroadcastAddress handles the nullable broadcast.
+
+# 4. Non-publishing version smoke test — exercises the Lerna 5 version path
+#    WITHOUT publishing to npm or touching git. --allow-branch "*" overrides the
+#    lerna.json `allowBranch: stable` guard for this one local run.
+#    Single line + quoted "*" so it runs the same in PowerShell, cmd, bash, zsh.
+npx lerna version --conventional-commits --no-push --no-git-tag-version --allow-branch "*" --yes
+git checkout -- packages   # discard the version/CHANGELOG file writes lerna just made
+```
+
+> **`npm run publish:testing` is NOT a dry run — it publishes to npm.**
+> `lerna publish` runs an `npm publish` (the `@ionic/*` packages under the
+> `testing` dist-tag); `--no-push`/`--no-git-tag-version` only suppress *git*
+> actions, not the registry publish. It also only runs from `stable` (the
+> `allowBranch` guard). Use step 4 above for a safe local check. Run
+> `publish:testing` only when you actually intend to push a `testing` prerelease
+> to npm, with valid npm credentials.
+
+The step-4 smoke test also reveals the **computed version bump** from the
+branch's conventional commits. Note it will show a `patch`/`minor` bump until
+the branch carries breaking-change commits (`feat!:` / `BREAKING CHANGE:`) —
+those, not `BREAKING.md`, are what make `@ionic/cli` land on `8.0.0` (see §1).
+
+> **Known platform note (pre-existing, unrelated to the release tooling):** on
+> **Windows**, one test in `integrations/cordova` asserts POSIX (`/`) path
+> separators and fails because `path.relative` returns `\` on Windows. It passes
+> on macOS/Linux (and therefore in CI). It is not introduced by these changes,
+> and the Cordova integration is slated for removal in v8.

.github/workflows/cd.yml

@@ -16,10 +16,18 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v3
+      - name: Guard against unfilled BREAKING.md placeholders
+        # The removal PRs fill in each command's entry. Block a stable publish
+        # if any <TODO placeholder would otherwise ship to users.
+        run: |
+          if grep -n '<TODO' BREAKING.md; then
+            echo "::error file=BREAKING.md::BREAKING.md still contains <TODO placeholders; each removal PR must fill in its entry before publishing."
+            exit 1
+          fi
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 18
           registry-url: https://registry.npmjs.org/
@@ -34,6 +42,10 @@ jobs:
           GIT_COMMITTER_NAME: Ionitron
           GIT_COMMITTER_EMAIL: hi@ionicframework.com
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # Required by `lerna version --create-release github` to create the
+          # GitHub Release for each published tag. The built-in token is
+          # sufficient (the workflow already grants `contents: write`).
+          GH_TOKEN: ${{ github.token }}
       - name: Sleep while npm takes its time
         run: sleep 20
       - name: GitHub Container Registry Login

.github/workflows/ci.yml

@@ -17,14 +17,14 @@ jobs:
       matrix:
         node:
           - 18.x
-          - 16.x
+          - 20.x
     steps:
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: ${{ matrix.node }}
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Restore Dependency Cache
-        uses: actions/cache@v3
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: ~/.npm
           key: ${{ runner.OS }}-dependency-cache-${{ hashFiles('**/package.json') }}

.github/workflows/docker-image.yml

@@ -7,10 +7,10 @@ jobs:
     name: Build and Deploy Docker Container with latest CLI
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 16.x
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
       - name: GitHub Container Registry Login

BREAKING.md

@@ -0,0 +1,128 @@
+# Breaking Changes
+
+This is a comprehensive list of the breaking changes introduced in the major
+version releases of the Ionic CLI.
+
+## Versions
+
+- [Version 8.x](#version-8x)
+
+> Older majors are archived under [`BREAKING_ARCHIVE/`](BREAKING_ARCHIVE) (e.g.
+> `BREAKING_ARCHIVE/v7.md`). When the next major begins, move the section below
+> into `BREAKING_ARCHIVE/v8.md` and start a fresh `Version 9.x` section here.
+
+## Version 8.x
+
+In version 8, the Ionic CLI is focused on the **Framework and Capacitor**
+workflows. The Appflow, Enterprise, and Cordova commands have been removed.
+
+- [Removed Commands](#removed-commands)
+
+### Removed Commands
+
+The following commands have been removed. Each entry records **what was
+removed**, **why**, and the **migration path / alternative**.
+
+> **Note:** The removal PRs are authored and coordinated separately. The entries
+> below are seeded placeholders — each removal PR should fill in the specifics
+> (the exact `diff`, the reason, and the migration link) for the command it
+> removes.
+
+#### `config`
+
+- **What:** The `config` command (and its `config get` / `config set` /
+  `config unset` subcommands) has been removed. _<TODO: confirm exact surface
+  removed in the removal PR.>_
+- **Why:** _<TODO: rationale — CLI configuration scope reduced for the
+  Framework/Capacitor-focused CLI.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `cordova`
+
+- **What:** The `cordova` command group has been removed. _<TODO: confirm exact
+  surface removed.>_
+- **Why:** _<TODO: Cordova retirement in favor of Capacitor.>_
+- **Migration:** Migrate to Capacitor. _<TODO: link to the Capacitor migration
+  guide.>_
+
+#### `enterprise`
+
+- **What:** The `enterprise` command group has been removed. _<TODO: confirm
+  exact surface removed.>_
+- **Why:** _<TODO: Ionic Enterprise tooling retirement.>_
+- **Migration:** _<TODO: point Enterprise users to current Appflow / Enterprise
+  tooling.>_
+
+#### `git`
+
+- **What:** The `git` command group has been removed. _<TODO: confirm exact
+  surface removed.>_
+- **Why:** _<TODO: tied to Appflow remote workflows being retired from the
+  CLI.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `init`
+
+- **What:** The `init` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: rationale.>_
+- **Migration:** _<TODO: alternative — e.g. `ionic start` / Capacitor init.>_
+
+#### `integrations` (Enterprise portion only)
+
+- **What:** The **Enterprise portion** of the `integrations` command has been
+  removed. **The Capacitor integration is kept.** _<TODO: confirm exact
+  subcommands/flags removed vs. retained.>_
+- **Why:** _<TODO: Enterprise integration retirement; Capacitor remains a
+  first-class workflow.>_
+- **Migration:** Continue using `ionic integrations enable capacitor`. _<TODO:
+  link.>_
+
+#### `link`
+
+- **What:** The `link` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: Appflow app-linking retirement.>_
+- **Migration:** _<TODO: point Appflow users to current Appflow tooling.>_
+
+#### `live-update`
+
+- **What:** The `live-update` command group has been removed. _<TODO: confirm
+  exact surface removed.>_
+- **Why:** _<TODO: Appflow Live Updates retirement from the CLI.>_
+- **Migration:** _<TODO: point users to current Appflow Live Updates tooling.>_
+
+#### `login`
+
+- **What:** The `login` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: Ionic account auth no longer needed by the CLI.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `logout`
+
+- **What:** The `logout` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: counterpart to `login` removal.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `repair`
+
+- **What:** The `repair` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: rationale.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `signup`
+
+- **What:** The `signup` command has been removed. _<TODO: confirm exact surface
+  removed.>_
+- **Why:** _<TODO: Ionic account flows removed from the CLI.>_
+- **Migration:** _<TODO: alternative / link.>_
+
+#### `ssh`
+
+- **What:** The `ssh` command group (and its subcommands) has been removed.
+  _<TODO: confirm exact surface removed.>_
+- **Why:** _<TODO: Appflow SSH key management retirement from the CLI.>_
+- **Migration:** _<TODO: point Appflow users to current Appflow tooling.>_