[#2720] Extracted a dedicated 'import-db' script reused by provision and ahoy.

[AlexSkrypnyk]

Closes #2720

Extracted a dedicated import-db router script and import-db-file worker script, reused by both provision and ahoy import-db. This mirrors the existing export-db/export-db-file pattern and fixes a silent no-op bug in ahoy import-db.

Changes

• New .vortex/tooling/src/import-db - host-aware router: on the host it runs docker compose exec -T cli .../import-db-file; inside the container it calls the worker directly (same is_host() pattern as export-db).
• New .vortex/tooling/src/import-db-file - worker that resolves the dump path from its argument or VORTEX_IMPORT_DB_FILE_DIR/VORTEX_DB_DIR + VORTEX_DB_FILE defaults, then runs drush sql:drop and pipes the dump into drush sql:connect. Refuses to run when the dump is missing or unreadable, so an unreadable file can never leave the site with the database dropped and nothing imported.
• .vortex/tooling/src/provision - provision_from_db() keeps its explicit dump-file check, the nested fallback-to-profile branch, and its in-context failure signal (Unable to import database from file. / Dump file … does not exist. / Site content was not changed.), and delegates only the actual drush sql:drop + drush sql:connect import to import-db-file. Provisioning behaviour and output are unchanged.
• .ahoy.yml - ahoy import-db now calls the new import-db router and gains an ahoy confirm guard. The old command set VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 and ran provision, which on an existing site with VORTEX_PROVISION_OVERRIDE_DB=0 silently preserved the database instead of replacing it.
• New BATS tests import-db.bats (4 cases) and import-db-file.bats (4 cases, including the missing-file and unreadable-file guards); provision.bats unchanged (drush call order is identical).
• Functional test SubtestAhoyTrait.php - updated the ahoy import-db expected output to the new script banners.
• Docs .vortex/docs/content/drupal/provision.mdx - removed a stale sentence that described ahoy import-db as using VORTEX_PROVISION_POST_OPERATIONS_SKIP.
• Installer snapshots regenerated for the .ahoy.yml change (139/139 clean on second pass).

Screenshots

N/A

Before / After

BEFORE
──────────────────────────────────────────────────────────────
  ahoy import-db [file]
  └─► provision (with VORTEX_PROVISION_POST_OPERATIONS_SKIP=1
                 and VORTEX_PROVISION_DB="$@")
        └─► provision_from_db()
              ├─ checks file exists
              ├─ drush sql:drop          ← inline, inside provision
              └─ $(drush sql:connect) < dump

  Behaviour: if VORTEX_PROVISION_OVERRIDE_DB=0 (the default on an
  existing site), provision SKIPS the drop+import entirely and
  silently exits — ahoy import-db was a no-op on live environments.

AFTER
──────────────────────────────────────────────────────────────
  ahoy import-db [file]   (confirm guard)
  └─► import-db  (router, host-side)
        ├─ on host  → docker compose exec -T cli import-db-file [file]
        └─ in CLI   → import-db-file [file]
                         ├─ resolve dump path
                         ├─ fail-fast if file missing or unreadable
                         ├─ drush sql:drop
                         └─ $(drush sql:connect) < dump

  provision
  └─► provision_from_db()
        ├─ explicit file check + fallback + failure signal (kept)
        └─► import-db-file [file]   ← same worker, no duplication

Summary by CodeRabbit

• New Features
  • Added a dedicated database import flow that shows clear start/finish status.
  • The import tooling now supports host or Docker execution, optional debug tracing, and prompts for confirmation before running.
• Bug Fixes
  • Prevents database import from running when the dump file is missing or not readable.
• Documentation
  • Updated environment variable guidance for database import behavior.
• Tests
  • Added unit tests covering argument handling, default dump selection, failure cases, and Docker vs local execution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cc95ff64-8436-4aef-bdbb-f3770eb27788

📥 Commits

Reviewing files that changed from the base of the PR and between f337e5e and b175021.

📒 Files selected for processing (2)

• .vortex/tooling/src/import-db-file
• .vortex/tooling/src/provision

---

Walkthrough

The PR adds a dedicated database import script, reuses it from provision, and routes ahoy import-db through a confirmation step and tooling check. Tests and docs were updated to match the new import flow and messages.

Changes

Database import flow

Layer / File(s)	Summary
Import worker and provision reuse .vortex/tooling/src/import-db-file, .vortex/tooling/src/provision, .vortex/tooling/tests/unit/import-db-file.bats, .vortex/docs/content/drupal/provision.mdx	The new worker script validates dump files, runs the Drush import, and replaces the inline provision import path; tests cover explicit, default, missing, and unreadable dump files, and the provisioning docs entry is shortened.
Ahoy command and router .ahoy.yml, .vortex/tooling/src/import-db, .vortex/tooling/tests/unit/import-db.bats, .vortex/tests/phpunit/Traits/Subtests/SubtestAhoyTrait.php	ahoy import-db now confirms replacement, requires tooling, and invokes the router script, which dispatches to the worker locally or through Docker; router tests and Ahoy output expectations were updated.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant AhoyImportDb as ahoy import-db
  participant RequireTooling as ahoy require-tooling
  participant ImportDb as src/import-db
  participant DockerCompose as docker compose
  participant ImportDbFile as import-db-file
  participant Drush as drush

  User->>AhoyImportDb: confirm database replacement
  AhoyImportDb->>RequireTooling: ahoy require-tooling
  AhoyImportDb->>ImportDb: run src/import-db "$@"
  alt RUN_ON_HOST=1
    ImportDb->>DockerCompose: docker compose exec -T cli ./vendor/drevops/vortex-tooling/src/import-db-file "$@"
    DockerCompose->>ImportDbFile: execute import-db-file
  else RUN_ON_HOST=0
    ImportDb->>ImportDbFile: run local import-db-file "$@"
  end
  ImportDbFile->>Drush: drush sql:drop
  ImportDbFile->>Drush: drush sql:connect < dump_file

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• drevops/vortex#2510: Touches the same import-db command surface and related command wiring/aliases.

Suggested labels

A3

Poem

🐰 I hopped through the dump-file gate,
and found one path for import fate.
The burrow now hums, both neat and bright,
while Drush does its work just right.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: extracting a dedicated import-db script reused by provision and Ahoy.
Linked Issues check	✅ Passed	The PR adds shared import-db scripts, updates provision to reuse them, and relinks ahoy import-db, matching #2720.
Out of Scope Changes check	✅ Passed	The changes stay focused on shared database import wiring, with only matching tests and docs updated.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/2720-extract-import-db

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.vortex/tooling/src/import-db:
- Line 7: The header comment in the import-db script is stale and contradicts
the router logic, since the dual-mode flow also handles the in-container branch.
Update the wording near the script header to describe that it routes between
host and container execution, and keep the description aligned with the branch
logic in the routing entrypoint so readers understand both paths.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3c7d5740-7e22-491d-95ae-8968779eead1

📥 Commits

Reviewing files that changed from the base of the PR and between 435ff4d and f337e5e.

⛔ Files ignored due to path filters (29)

• .vortex/installer/tests/Fixtures/handler_process/_baseline/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/modules_no_sdc_devel/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/modules_none/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/theme_claro/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/theme_olivero/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/theme_stark/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_fe_lint/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_fe_lint_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_fe_lint_no_theme/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_fe_lint_no_theme_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_behat/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_eslint_no_theme/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_jest/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_jest_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_rector/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_no_stylelint_no_theme/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**
• .vortex/installer/tests/Fixtures/handler_process/tools_none/.ahoy.yml is excluded by !.vortex/installer/tests/Fixtures/**

📒 Files selected for processing (8)

• .ahoy.yml
• .vortex/docs/content/drupal/provision.mdx
• .vortex/tests/phpunit/Traits/Subtests/SubtestAhoyTrait.php
• .vortex/tooling/src/import-db
• .vortex/tooling/src/import-db-file
• .vortex/tooling/src/provision
• .vortex/tooling/tests/unit/import-db-file.bats
• .vortex/tooling/tests/unit/import-db.bats

[github-actions]

📖 Documentation preview for this pull request has been deployed to Netlify:

https://6a3da69d9c879e76b9009afb--vortex-docs.netlify.app

This preview is rebuilt on every commit and is not the production documentation site.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.22%. Comparing base (435ff4d) to head (b175021).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2728      +/-   ##
==========================================
- Coverage   86.67%   86.22%   -0.45%     
==========================================
  Files          96       89       -7     
  Lines        4719     4560     -159     
  Branches       47        3      -44     
==========================================
- Hits         4090     3932     -158     
+ Misses        629      628       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.55% (204/207)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[AlexSkrypnyk]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.55% (204/207)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)