wordmove-ng 6.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f483b0f5d6fbc250704d0f32134a73eef315ab0cc2b31d8313a1e6553ad1aaa
+  data.tar.gz: dfd3302b3678fac11044ea5a51405b57c4aab7369171f9d04d6b1e932476bd8a
+SHA512:
+  metadata.gz: fdc7e665dbbe4e97cd9d58310cad0c23ca0cde8870da5470390aa4ac0e02285fa78be59676658b60a93490e86b7addc807cb9007821bd94787b2bbf843a4b9e8
+  data.tar.gz: e33568402ef5f6638f8fe0748d29aeedd724af84f84ea9395dd7c7b9f2d89cbc051437c5ea3cf2afe317a248cc21dee1fabfb3cc43f8d236e5506a5c74359f6c

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+
+> A clear and concise description of what the bug is.
+
+**Wordmove command**
+
+> Command used on the CLI: (e.g.: `wordmove-ng pull --all --no-db`)
+
+**Expected behavior**
+
+> A clear and concise description of what you expected to happen.
+
+**movefile.yml**
+
+> Paste (removing personal data) the interesting part, if any, of your `movefile.yml` formatting it inside a code block with `yml` syntax and double checking the indentation.
+
+**Exception/trace**
+
+> Paste (removing personal data) the entire trace of error/exception you encountered, if any
+
+**Environment (please complete the following information):**
+
+- OS:
+- Ruby: (`ruby --version`)
+- wordmove-ng: (`wordmove-ng --version`)
+
+**Doctor**
+
+* [x] running the `wordmove-ng doctor` command returns all green
+
+> (If it is not, report the error you got.)

data/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussion
+    url: https://github.com/tekgnosis-net/wordmove-ng/discussions/new?category=general
+    about: Start an open discussion and ask for help
+  - name: Idea or feature request
+    url: https://github.com/tekgnosis-net/wordmove-ng/discussions/new?category=ideas
+    about: Propose your own ideas. We'll triage them and decide if bring them to the issue tracker
+  - name: Help
+    url: https://github.com/tekgnosis-net/wordmove-ng/discussions/new?category=q-a
+    about: Ask for help if you're stuck with wordmove-ng or integrating it with your workflow

data/.github/stale.yml

@@ -0,0 +1,18 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 60
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 7
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - 💡 Feature
+  - 🐛 Bug
+  - 🏥 Triage
+# Label to use when marking an issue as stale
+staleLabel: status:wontfix
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: false

data/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+# Release automation.
+#
+# 1. release-please watches master. From Conventional Commits it opens (and keeps
+#    updating) a "release PR" that bumps lib/wordmove/version.rb and CHANGELOG.md.
+#    Merging that PR creates the vX.Y.Z tag and the GitHub release.
+# 2. The publish job then builds the gem and pushes it to rubygems.org with
+#    trusted publishing (OIDC, no API key) and attaches the .gem to the release.
+#
+# The publish job also runs when a v* tag is pushed by hand, which is how the
+# very first release (v6.0.0) is cut.
+#
+# One-time setup (see README "Releasing"):
+#   - rubygems.org: pending trusted publisher for gem wordmove-ng, repository
+#     tekgnosis-net/wordmove-ng, workflow release.yml, environment release
+#   - GitHub: environment "release"; Actions setting "Allow GitHub Actions to
+#     create and approve pull requests" enabled (needed by release-please)
+
+name: Release
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-please:
+    if: github.ref == 'refs/heads/master' && github.event_name != 'workflow_dispatch' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: [release-please]
+    # Runs after release-please created a release, or on a manually pushed tag.
+    # The `always()` is needed because release-please is skipped on tag pushes.
+    if: >-
+      always() && (
+        needs.release-please.outputs.release_created == 'true' ||
+        startsWith(github.ref, 'refs/tags/v')
+      )
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write   # upload the .gem to the GitHub release
+      id-token: write   # rubygems.org trusted publishing
+    steps:
+      # `rake release` (run by release-gem) tags and pushes, so it needs a real
+      # branch checkout, not a detached tag.
+      - uses: actions/checkout@v5
+        with:
+          ref: master
+          fetch-depth: 0
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Verify the tag points at the head of master
+        env:
+          TAG: ${{ needs.release-please.outputs.tag_name || github.ref_name }}
+        run: |
+          git fetch --tags --force
+          tag_commit="$(git rev-parse "refs/tags/$TAG^{commit}")"
+          head_commit="$(git rev-parse HEAD)"
+          if [ "$tag_commit" != "$head_commit" ]; then
+            echo "::error::$TAG points at $tag_commit but master is at $head_commit; tag the head of master."
+            exit 1
+          fi
+          version="$(ruby -Ilib -e 'require "wordmove/version"; print Wordmove::VERSION')"
+          if [ "v$version" != "$TAG" ]; then
+            echo "::error::lib/wordmove/version.rb says $version but the tag is $TAG."
+            exit 1
+          fi
+
+      - name: Run the test suite once more on the release commit
+        run: bundle exec rake
+
+      - name: Build and push the gem to rubygems.org
+        uses: rubygems/release-gem@v1
+
+      - name: Attach the gem to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.release-please.outputs.tag_name || github.ref_name }}
+        run: gh release upload "$TAG" pkg/*.gem --clobber

data/.github/workflows/ruby.yml

@@ -0,0 +1,41 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version:
+          - "3.0"
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "3.4"
+          - "4.0"
+
+    steps:
+    - uses: actions/checkout@v5
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+spec/coverage
+spec/examples.txt
+test/tmp
+test/version_tmp
+tmp
+.vs/

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "6.0.0"
+}

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,50 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/*'
+    - 'vendor/**/*'
+    - 'pkg/**/*'
+    - 'supertool/**/*'
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - 'spec/factories/*.rb'
+    - '*.gemspec'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/AbcSize:
+  Max: 40
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Kept from the original config; the specs are written against STDOUT.
+Style/GlobalStdStream:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,89 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --no-offense-counts --no-auto-gen-timestamp`
+# using RuboCop version 1.90.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+    - 'lib/wordmove/deployer/ssh.rb'
+    - 'lib/wordmove/movefile.rb'
+    - 'spec/cli_spec.rb'
+    - 'spec/deployer/base_spec.rb'
+    - 'spec/generators/movefile_adapter_spec.rb'
+    - 'spec/logger/logger_spec.rb'
+    - 'spec/prerequisites_spec.rb'
+    - 'spec/sql_adapter/wpcli_spec.rb'
+
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+    - 'lib/wordmove/doctor/mysql.rb'
+
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 33
+
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+    - 'lib/wordmove/deployer/ssh.rb'
+
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/wordmove/deployer/base.rb'
+
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: infinite?, nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/wordmove/doctor/movefile.rb'
+    - 'lib/wordmove/guardian.rb'
+
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/IdenticalConditionalBranches:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/OpenStructUse:
+  Exclude:
+    - 'lib/wordmove/generators/movefile_adapter.rb'
+
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: respond_to_missing?
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/wordmove/hook.rb'
+    - 'lib/wordmove/movefile.rb'
+
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'lib/wordmove/deployer/ssh.rb'

data/.ruby-gemset

@@ -0,0 +1 @@
+wordmove-ng

data/.ruby-version

@@ -0,0 +1 @@
+3.4.9

data/.vscode/launch.json

@@ -0,0 +1,73 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug Local File",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/main.rb"
+        },
+        {
+            "name": "Listen for rdebug-ide",
+            "type": "Ruby",
+            "request": "attach",
+            "cwd": "${workspaceRoot}",
+            "remoteHost": "127.0.0.1",
+            "remotePort": "1234",
+            "remoteWorkspaceRoot": "${workspaceRoot}"
+        },
+        {
+            "name": "Rails server",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rails",
+            "args": [
+                "server"
+            ]
+        },
+        {
+            "name": "RSpec - all",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "args": [
+                "-I",
+                "${workspaceRoot}"
+            ]
+        },
+        {
+            "name": "RSpec - active spec file only",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "args": [
+                "-I",
+                "${workspaceRoot}",
+                "${file}"
+            ]
+        },
+        {
+            "name": "RSpec - active test only",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/rspec",
+            "args": [
+                "-I",
+                "${workspaceRoot}",
+                "${file}:${lineNumber}"
+            ]
+        },
+        {
+            "name": "Cucumber",
+            "type": "Ruby",
+            "request": "launch",
+            "cwd": "${workspaceRoot}",
+            "program": "${workspaceRoot}/bin/cucumber"
+        }
+    ]
+}

data/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to wordmove-ng are documented here. The project follows
+[Semantic Versioning](https://semver.org). Releases of the original Wordmove (up to 5.2.2)
+are listed at https://github.com/welaika/wordmove/releases; the kokiddp fork's changes
+between 5.2.2 and this project are summarised under 6.0.0.
+
+## 6.0.0 (unreleased)
+
+First release as an independent project. Breaking changes are marked **breaking**.
+
+### Identity
+
+- **breaking** Gem renamed to `wordmove-ng`, executable renamed to `wordmove-ng`. The Ruby
+  namespace stays `Wordmove`. The legacy `wordmove` gem can remain installed alongside.
+- **breaking** Ruby 3.0 or newer is required. CI covers 3.0 through 4.0.
+- New logo based on the original emblem and wordmark with an "ng" badge.
+
+### SSH transport
+
+- Remote commands, single-file transfers, deletes and remote hooks use the system `ssh` and
+  `scp` binaries (`Wordmove::SshRunner`) instead of Net::SSH. Key authentication now behaves
+  exactly like the rsync file sync: ssh-agent, `~/.ssh/config`, RSA SHA-2 signatures and
+  `ProxyJump` all work. Fixes the database step prompting for a password while rsync
+  succeeded, caused by net-ssh 6 lacking RSA SHA-2 client authentication.
+- Connections run with `BatchMode=yes` unless `ssh.password` is set (then `sshpass`). A
+  failed key authentication is an error with the failing command, never a prompt.
+- `ssh.gateway` is passed as `ssh -J`. `gateway.password` cannot be honoured and is ignored;
+  doctor warns about it.
+- Remote commands run through `sh -c`, so non-POSIX remote login shells (fish, csh) work.
+- Removed the net-ssh OpenSSL 3 compatibility shim and the `ed25519` and `bcrypt_pbkdf`
+  dependencies, which are no longer needed.
+
+### Database sync
+
+- **breaking** `push -d` imports the dump on the remote and runs `wp search-replace` there.
+  The local database is never modified during a push. WP-CLI is required on the remote.
+- **breaking** FTP and SFTP support removed, together with the PHP dump/import scripts and
+  the regex-based dump rewriter (`sql_adapter: default`). A movefile with an `ftp` block
+  raises a clear error.
+- `global.sql_adapter` is ignored (accepted with a warning). The `global` section is now
+  optional. `database.charset` removed from the schema.
+- Prerequisites (`gzip`, `mysql`/`mariadb`, `mysqldump`/`mariadb-dump`, `wp`) are probed on
+  both sides before any backup or dump; a missing program aborts with a list.
+- New `global.maintenance_mode` (or `WORDMOVE_MAINTENANCE_MODE=1`) wraps the target's
+  import and search-replace in `wp maintenance-mode activate`/`deactivate`, deactivating
+  even on failure. Default off.
+- Warns when one search-replace term is a prefix of another; doctor reports it as an error.
+- If the remote adaptation fails after the import, the log names the pre-import backup.
+- Collations are normalised once per dump (previously twice on push).
+
+### Doctor
+
+- Tests non interactive SSH authentication for every SSH environment and prints the failing
+  command and stderr.
+- Probes each remote for `rsync`, `gzip`, `mysql`/`mariadb`, `mysqldump`/`mariadb-dump` and
+  `wp`.
+- Reports `ftp` blocks, prefix collisions and gateway passwords.
+
+### Other
+
+- `--result-file` and gzip paths are shell-escaped with Shellwords (a `"` or `$` in
+  `wordpress_path` no longer breaks the dump or import).
+- Hook and Guardian output mask movefile secrets like the deployer log.
+- Simulate mode no longer appends `--dry-run` to the shared `rsync_options` string.
+- Rubocop 1.x with the pre-existing backlog grandfathered in `.rubocop_todo.yml`; the default
+  rake task runs specs and rubocop. Development dependencies moved to the Gemfile.
+
+### Inherited from the kokiddp fork (unreleased upstream changes since wordmove 5.2.2)
+
+- Ruby 3.x and 4.0 compatibility, stdlib gems declared explicitly.
+- MariaDB binaries preferred, sandbox-header stripping, `--binary-mode`,
+  `SET FOREIGN_KEY_CHECKS=0` and trailing `COMMIT;` on import.
+- `database.socket` and `database.port`; `init` splits `DB_HOST` values with a socket or port.
+- Built-in `utf8mb3` collation and charset fallbacks, overridable in the movefile.
+- `wp` called with `--allow-root`; local vhost detected from `wp-config.php` or `wp option`.
+- Command summaries in the log instead of full shell scripts; secrets masked.
+- Paths with spaces supported throughout.

data/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+wordmove-ng is a Ruby gem / Thor CLI (executable `wordmove-ng`) that mirrors WordPress installs
+(files + database) between a local checkout and remote SSH hosts described in a `movefile.yml`.
+It is the independent successor of welaika/wordmove (via the kokiddp fork); the Ruby namespace is
+still `Wordmove` and code lives under `lib/wordmove/`. Version lives in `lib/wordmove/version.rb`;
+bumping it is a release step, not part of feature work.
+
+## Commands
+
+```bash
+bundle install                      # deps (Gemfile.lock is gitignored)
+bundle exec rake                    # default task = RSpec suite + rubocop (what CI runs)
+bundle exec rake spec               # specs only
+bundle exec rspec spec/movefile_spec.rb            # one file
+bundle exec rspec spec/movefile_spec.rb:42         # one example by line
+bundle exec rspec -e "some example description"    # by description
+bundle exec rake rubocop            # lint (rubocop 1.x, NewCops enabled; backlog lives in .rubocop_todo.yml)
+bin/wordmove-ng --version           # run the CLI from source without installing
+rake install                        # build + install the gem locally
+```
+
+- `.rspec` already sets `--require spec_helper --color`; documentation formatter and
+  SimpleCov are enabled in `spec/spec_helper.rb`.
+- CI (`.github/workflows/ruby.yml`) runs `bundle exec rake` on Ruby 3.0 through 4.0. Code must
+  run on Ruby 3.0 **and** Ruby 4 (see the `StringScanner#peep` shim in `lib/wordmove.rb` and the
+  explicit `ostruct`/`base64`/`mutex_m`/`logger` runtime deps in the gemspec). Local
+  `.ruby-version` is 3.4.9. Dev dependencies live in the Gemfile, not the gemspec.
+- Fix new rubocop offences rather than adding to `.rubocop_todo.yml`; the todo file only
+  grandfathers the pre-6.0 backlog.
+- `pry-byebug` is loaded optionally in specs; a `LoadError` there is tolerated.
+
+## Architecture (request flow)
+
+`exe/wordmove` -> `Wordmove::CLI` (Thor, `lib/wordmove/cli.rb`) -> for `push`/`pull`:
+
+1. `Deployer::Base.deployer_for(cli_options)` builds a `Movefile`, loads dotenv, merges the
+   YAML options with CLI options, resolves the environment, then returns `Deployer::SSH`.
+   An `ftp` block raises `NoAdapterFound` with a removal message; a leftover
+   `global.sql_adapter` key only warns.
+2. `Hook.run(action, :before, options)` runs local/remote hooks from the movefile.
+3. `Guardian#allows(task)` checks `<env>.forbid.<push|pull>.<task>`; forbidden tasks are
+   logged and skipped, not raised.
+4. For each selected task (`wordpress uploads themes plugins mu_plugins languages db`) the CLI
+   calls `deployer.send("push_#{task}")` / `pull_…`. `--all` selects every task unless a flag is
+   explicitly `false`.
+5. `Hook.run(action, :after, options)`.
+
+Key pieces:
+
+- **`Movefile`** (`lib/wordmove/movefile.rb`): finds `{M,m}ovefile{,.yml,.yaml}` walking up
+  until `/` or a dir containing `wp-config.php`; evaluates ERB then `YAML.safe_load`; owns
+  environment selection (`-e` required when more than one remote env) and `secrets` (passwords,
+  hosts, vhosts, wordpress paths) that `Logger` masks in all output. Doctor validates it with
+  Kwalify against the three schemas in `lib/wordmove/assets/`.
+- **`Deployer::Base`**: shared logic. Task methods and `local_/remote_<type>_dir` helpers are
+  metaprogrammed from lists; add a component by extending those lists plus the CLI's
+  `wordpress_options` and `WordpressDirectory::Path`. Builds `mysqldump`/`mysql` commands
+  (prefers `mariadb-dump`/`mariadb` when present), `Shellwords.escape`s every arg, and
+  rewrites `utf8mb3*` collations/charsets in dumps via `normalize_collations!`
+  (overridable through `global.collation_fallbacks` / `global.charset_fallbacks`).
+- **`Deployer::SSH`** (the only deployer): directory sync is rsync via Photocopier; the
+  transfer root is always the WordPress root and per-component sync is expressed with
+  computed include/exclude path lists, so `exclude` entries in the movefile are always
+  relative to the WP root. Remote commands, single-file `scp` transfers, deletes and remote
+  hooks go through `Wordmove::SshRunner` (`lib/wordmove/ssh_runner.rb`), which shells out to
+  the system `ssh`/`scp` with `BatchMode=yes` unless `ssh.password` is set (then `sshpass`)
+  and wraps every remote command in `sh -c`. Do not reintroduce Net::SSH: Photocopier pins
+  net-ssh 6, which cannot do RSA SHA-2 auth. `-s/--simulate` becomes `rsync --dry-run` and
+  short-circuits DB steps.
+- **DB sync** (same class): symmetric in both directions: probe prerequisites on both
+  sides, back up the target, dump the source, import on the target, then `wp search-replace`
+  for `vhost` and `wordpress_path` *on the target* (locally for pull, over SSH for push),
+  optionally inside `wp maintenance-mode`. The source DB is never written. Nothing rewrites
+  dump text apart from `normalize_collations!`.
+- **`Doctor`** (`lib/wordmove/doctor/*`): `wordmove-ng doctor` validates the movefile schema
+  (rejecting `ftp`, reporting prefix collisions), then checks local mysql, wp-cli and rsync,
+  and per SSH environment: batch-mode auth, remote prerequisites via `Prerequisites`, and
+  gateway-password misuse.
+- **`Generators::Movefile`**: `wordmove-ng init` wizard; reads `wp-config.php` and detects the
+  local vhost.
+- **`Prerequisites`** (`lib/wordmove/prerequisites.rb`): one `sh` probe listing missing
+  programs; `DB_SOURCE`/`DB_TARGET`/`REMOTE_ALL` requirement sets shared by deployer and
+  doctor.
+- **Knobs**: `global.maintenance_mode` (env override `WORDMOVE_MAINTENANCE_MODE`),
+  `global.collation_fallbacks`, `global.charset_fallbacks`. Add new toggles as movefile keys
+  with an env override and document them in README + CHANGELOG in the same commit.
+
+## Conventions worth knowing
+
+- **Commit messages are Conventional Commits** (`feat:`, `fix:`, `feat!:`/`BREAKING CHANGE:`,
+  `docs:`, `chore:`, `ci:`, `test:`, `refactor:`). release-please derives the version bump
+  and CHANGELOG from them; never edit `lib/wordmove/version.rb` or `CHANGELOG.md` by hand.
+  Releases are published to rubygems.org by `.github/workflows/release.yml` (trusted
+  publishing, no secrets).
+
+- Every shell fragment that includes user/config data goes through `Shellwords.escape`
+  (or `Shellwords.split` for user-supplied option strings). Secrets must never appear in
+  log lines except through `Logger`, which masks `Movefile#secrets`.
+- Shell failures are detected via `$CHILD_STATUS.success?` and raised as
+  `ShellCommandError`; custom exceptions live in `lib/wordmove/exceptions.rb`.
+- `simulate?` must be honoured by every new side-effecting step (log the step, then return).
+- Specs stub `Wordmove::SshRunner` (instance_double), `Photocopier::SSH.new` and
+  `Prerequisites.missing_*` rather than touching SSH; `spec/deployer/ssh_db_spec.rb` records
+  every local and remote command in order and asserts on the sequence.
+  Movefile fixtures live in `spec/fixtures/movefiles/`; use `movefile_path_for("name")` from
+  `spec/support/fixture_helpers.rb`. `silence_stream` in `spec_helper.rb` quiets noisy output.
+- Rubocop limits: 100-col lines, 20-line methods, ABC 40. `rubocop:disable-next` is used
+  sparingly around genuinely long orchestration methods (see `Hook.run`).
+- The untracked `supertool/` directory is local tooling, not part of the gem.