Add —only flag for files-pull, limiting scope

[WPprodigy]

NOTE: This is based on top of #262 for now, will rebase against trunk after merging the other PR)

The PR adds a new —only SRC flag, allowing for specifying which folders/files should be imported, allowing you to limit an import:

# just userland, no core
--only :wp-content:

# several subtrees (comma-separated)
--only :wp-plugins:,:wp-content:/themes,:wp-uploads:

# scope + placement together: only wp-content, landed un-nested
--only :wp-content: --remap :wp-content: /srv/htdocs/wp-content

• SOURCE uses the same :token: convention as --remap (or a raw absolute path). Each token auto-resolves to the real source location from preflight — including relocated components (a moved uploads/plugins dir) and wp-config.php when it lives above ABSPATH.
• Available source tokens: :wp-content:, :wp-plugins:, :wp-mu-plugins:, :wp-uploads:, :wp-config:, :abspath:. Can append a sub-path after any token (e.g. :wp-content:/themes).
• Scoped pulls only delete within scope, so the local index accumulates as a union across scoped runs.

Testing

You'll need a source site with the reprint exporter installed.

DOCROOT=/tmp/remap-test  STATE=/tmp/remap-state
URL="https://YOUR-SITE.com/?site-export-api"  SECRET="<migration secret>"

php importer/import.php preflight  "$URL" --state-dir="$STATE" --fs-root="$DOCROOT" --secret="$SECRET"

# resumes; exits non-zero while partial
php importer/import.php files-pull "$URL" --state-dir="$STATE" --fs-root="$DOCROOT" --secret="$SECRET" --only :wp-content:

Confirm the scope was respected. Try again with --only :wp-plugins:, and note that the prev-imported themes/uploads aren't deleted.

[github-actions]

Pull pipeline performance — large-directory

Site: large-directory · 2,000+ plus targeted file-transfer scenarios files · 10,000 posts · 25,000 postmeta · PHP 8.5.7

Stage	PR	trunk	Δ	Status	Details
playground-sqlite-db-pull	9.15 s	9.35 s	⚪ -196 ms (-2.1%)	✓	condition=db-pull in PHP.wasm runtime=php.wasm 8.3 wp_mysql_parser=enabled mode=lexer native_lexer=verified native_token_stream=WP_MySQL_Native_Token_Stream native_token_count=18 native_parser=selected trunk: condition=db-pull in PHP.wasm runtime=php.wasm 8.3 wp_mysql_parser=enabled mode=lexer native_lexer=verified native_token_stream=WP_MySQL_Native_Token_Stream native_token_count=18 native_parser=selected
playground-sqlite-db-apply	3.69 s	3.57 s	⚪ +118 ms (+3.3%)	✓	condition=db-apply to SQLite in PHP.wasm runtime=php.wasm 8.3 wp_mysql_parser=enabled mode=parser native_lexer=verified native_token_stream=WP_MySQL_Native_Token_Stream native_token_count=18 native_parser=verified native_ast=WP_MySQL_Native_Parser_Node sqlite_driver_parser=verified trunk: condition=db-apply to SQLite in PHP.wasm runtime=php.wasm 8.3 wp_mysql_parser=enabled mode=parser native_lexer=verified native_token_stream=WP_MySQL_Native_Token_Stream native_token_count=18 native_parser=verified native_ast=WP_MySQL_Native_Parser_Node sqlite_driver_parser=verified
Total	12.84 s	12.92 s	⚪ -77 ms (-0.6%)

_{Numbers carry runner noise; treat single-run deltas as directional, not authoritative.}

_{📈 Trunk performance history — commit-by-commit timeline.}

[Copilot]

Pull request overview

This PR adds a --only SRC flag to the files-pull command, allowing users to limit file imports to specific folders/files (e.g., --only wp-content or --only wp-content/plugins,wp-content/themes). It builds on top of the --remap infrastructure from PR #262, reusing the WP-path resolution logic while adding scope-aware deletion in the diff reconciliation loop.

Changes:

• New resolve_scope() and in_scope() methods for resolving WP-layout paths to real source prefixes and checking membership, with detached-component expansion and prefix collapse.
• Scope-guarded delete drains in diff_indexes_and_build_fetch_list() so out-of-scope local files survive across scoped runs, and get_export_directories() returns scope prefixes directly when active.
• Extraction of detached_component_sources() as a shared helper (refactored from resolve_remap), addition of wp-config.php to the component source paths, and CLI option registration.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
packages/reprint-importer/src/import.php	Core implementation: $scope property, resolve_scope(), in_scope(), detached_component_sources() extraction, scoped download_remote_index/diff_indexes_and_build_fetch_list/get_export_directories, wp-config.php in component paths, CLI option definition
tests/Import/OnlyScopeTest.php	Unit tests for scope resolution, detached-component expansion, prefix collapse, and scoped enumeration
tests/Import/OnlyScopedDiffTest.php	Integration test verifying the diff loop preserves out-of-scope files while deleting in-scope orphans
tests/Import/OnlyCliParseTest.php	CLI parsing test confirming --only is recognized in both --only=VAL and --only VAL forms

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.