Merge pull request Automattic#841 from Automattic/feat/840-plan-first-import

Unify imports behind a plan-first ability

AI assistance disclosure: OpenAI gpt-5.6-sol via OpenCode implemented and verified the canonical import contract and compatibility repairs. Chris Huber reviewed and remains responsible for every line.

Author: chubes4

README.md

@@ -169,7 +169,7 @@ URL intake rules:
 
 - Every built-in URL import collects the bounded site through the resumable batch engine. It reads the origin's `/sitemap.xml`, follows same-origin HTML links, and collects directly referenced page assets and nested CSS assets.
 - SSI owns collection, batch, deadline, asset, byte, pacing, and script-policy defaults. Hosts can adjust this policy with the `static_site_importer_url_batch_import_args` filter.
-- The first `static-site-importer/import-url` call returns an opaque `import_id`. To continue a pending run, call the same ability with the normalized URL and import intent plus that ID. SSI resolves the server-owned workspace and validates the URL, import options, and current user; no filesystem path is accepted or returned.
+- `static-site-importer/import` accepts `{ source: { type: "url", url, import_id? }, operation }`. The first URL apply returns an opaque `import_id`; continuation supplies that ID in the same source envelope. SSI resolves the server-owned workspace and validates the URL, import options, and current user; no filesystem path is accepted or returned.
 - URL collection uses the frozen static artifact policy: executable and data scripts are omitted with reason-coded provenance because the server-rendered output does not require them.
 - Registered source-exclusion rules remove non-authored platform chrome before asset discovery and compilation. Each removal records selector, provider, reason, and before/after hashes under `source_metadata.collection.source_exclusions`; set `exclude_platform_chrome=false` to preserve the raw source.
 - Extensions can add or replace source-exclusion rules with the `static_site_importer_source_exclusion_rules` filter. Rules use stable ID selectors and reason-coded categories so removals remain explicit and auditable.
@@ -252,6 +252,8 @@ This materializer is intentionally generic: WooCommerce is the first plugin-back
 
 ## CLI Usage
 
+The canonical ability uses `source.type` (`artifact`, `url`, or `upload`) and `operation` (`plan` or `apply`). Artifact planning returns the canonical WordPress site plan, diagnostics, quality evidence, and source provenance without writing to the destination. Upload sources contain an opaque `upload_ref` resolved only by the server-side `static_site_importer_resolve_upload_reference` filter; callers never provide filesystem paths.
+
 ```bash
 wp static-site-importer import-theme /path/to/site/index.html \
   --slug=wordpress-is-dead \

composer.json

@@ -80,7 +80,7 @@
   "prefer-stable": true,
   "config": {
     "platform": {
-      "php": "8.2.0"
+      "php": "8.1.0"
     },
     "sort-packages": true
   }

composer.lock

@@ -6,6 +6,7 @@
     "tests/smoke-ability-error-report-summary.php": { "environment": "standalone-php" },
     "tests/smoke-ability-import-success-diagnostics.php": { "environment": "standalone-php" },
     "tests/smoke-ability-registration-idempotent.php": { "environment": "standalone-php" },
+    "tests/smoke-canonical-import-ability.php": { "environment": "standalone-php" },
     "tests/smoke-companion-plugin-js.php": { "environment": "standalone-php" },
     "tests/smoke-companion-plugin.php": { "environment": "standalone-php" },
     "tests/smoke-contact-layout-transformer.php": { "environment": "standalone-php" },