docs: v4 migration & architecture plan

[steveukx]

Adds docs/V4-MIGRATION-PLAN.md — the agreed plan and architecture for simple-git@4, to act as the living reference for the stacked PRs landing on canary/v4.

Covers

• Tooling: Yarn 4 → pnpm workspaces (no lerna exists today); keep changesets; rename publish → publishConfig; drop build:pkg + devtools/package-json.ts; remove all babel incl. @simple-git/babel-config.
• Test runner: jest + babel-jest → vitest (incl. the mock-child-process migration).
• Build: Vite library mode (es/cjs/umd) with the legacyExportFormat plugin so the CJS bundle supports both require('simple-git') and { simpleGit } = require('simple-git').
• Breaking removals: simple-git/promise + gitP; trailing callback arguments (replaced by a loud throw guard pointing at the upgrade doc).
• Task redesign: executor-agnostic task descriptors ({ commands, format, parser, onError? }); new git.run / git.raw / git.stream; existing methods retained as thin wrappers; new simple-git/tasks subpath; co-located per-task types.
  • run<R>(...tasks: [...GitTask<unknown>[], GitTask<R>]): Promise<R> — infers the result from the last task (no any).
  • raw keeps a backward-compatible trailing-Options overload with a zero-length string prefix.
• Security model (breaking): deny-by-default per-task environment filtering (strip GIT_* / GitEnvKeys unless allow-listed via allowEnvironment, built at spawn time so the task fails — not .env()); deny-by-default git config writes via allowConfigWrite (wildcards), with spreadable convenience presets (e.g. allowConfigWriteUser) — nothing bypasses the allow-list.
• Docs: build on Simple Git Documentation Site #1123's Astro + Starlight scaffold; API reference auto-generated from TSDoc.
• Acceptance gate (§0.1): every existing test must still pass, ported to vitest, except those that exclusively cover the two removed interfaces.

Docs-only; no code changes.

---

Generated by Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: f87b332

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR