feat(cli): import site archives larger than the instance size limit via --split (#484)

Add multi-part site archive import to b2c job import. --split (with
optional --max-size, default 190mb) breaks a large directory import into
smaller archives imported sequentially: order-sensitive metadata/XML
first (kept together, or split at data-unit boundaries in dependency
order), then static assets packed by compressed size. Non-split imports
that exceed the limit warn and recommend --split. SDK adds
siteArchiveImportSplit().

W-22899416

Author: clavery

.changeset/multi-part-site-import.md

@@ -0,0 +1,11 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+'@salesforce/b2c-agent-plugins': patch
+---
+
+`b2c job import` now supports `--split` for importing directories larger than the instance archive size limit. With `--split` (and optional `--max-size`, default `190mb`), the import is broken into several smaller archives: order-sensitive metadata/XML is imported first — kept together when it fits, otherwise split at data-unit boundaries in dependency order — followed by static assets packed by compressed size. A normal import that exceeds the limit now warns and recommends `--split`.
+
+Example: `b2c job import ./big-site-data --split --max-size 150mb`
+
+The SDK adds a corresponding `siteArchiveImportSplit()` operation.

docs/cli/jobs.md

@@ -280,6 +280,8 @@ In addition to [global flags](./index#global-flags):
 |------|-------------|---------|
 | `--keep-archive`, `-k` | Keep archive on instance after import | `false` |
 | `--remote`, `-r` | Target is a filename already on the instance (in Impex/src/instance/) | `false` |
+| `--split`, `-s` | Split a large directory import into multiple archive parts to stay under the instance size limit | `false` |
+| `--max-size` | Per-archive size limit for `--split` (e.g. `190`, `190mb`, `512kb`; a bare number is MiB) | `190mb` |
 | `--timeout`, `-t` | Timeout in seconds | No timeout |
 | `--wait`, `-w` | Wait for import job to complete | `true` |
 | `--show-log` | Show job log on failure | `true` |
@@ -310,6 +312,12 @@ b2c job import ./my-site-data 'libraries/**'
 
 # Mix sites and libraries
 b2c job import ./my-site-data sites/RefArch 'libraries/*'
+
+# Split a large import that exceeds the instance archive size limit
+b2c job import ./big-site-data --split
+
+# Split with a custom per-archive size limit
+b2c job import ./big-site-data --split --max-size 150mb
 ```
 
 ### Notes
@@ -319,6 +327,21 @@ b2c job import ./my-site-data sites/RefArch 'libraries/*'
 - By default, the archive is deleted after successful import (use `--keep-archive` to retain)
 - When `PATHS` are given, only those files/directories are included in the archive — their location under `TARGET` is preserved (e.g. `sites/RefArch/...` stays at `sites/RefArch/...`).
 
+### Importing archives larger than the instance limit
+
+A B2C Commerce instance rejects a single import archive above its size limit (typically 200 MB). The `--split` flag works around this **for directory imports** by importing the data in multiple smaller archive parts:
+
+1. **Metadata/XML first.** All order-sensitive XML (catalogs, libraries, sites, `meta`, etc.) is imported first, kept together in a single archive when it fits. Keeping it together means the import job resolves all internal references and dependency ordering within one archive. If the XML alone exceeds the limit, it is split at top-level data-unit boundaries (e.g. `catalogs`, `libraries`, `sites`) in dependency order — never splitting an individual unit, so a catalog and its internal references always stay together.
+2. **Static assets after.** Static resources (anything under a `static/` folder — images, fonts, binaries) are deferred into subsequent archive parts, packed by **compressed** size. They are order-independent and attach to the catalogs/libraries created by the metadata import.
+
+Parts are imported **sequentially** and the command stops on the first failure.
+
+Packing is by estimated compressed size (already-compressed file types such as JPG/PNG/ZIP are measured as stored). The default per-part ceiling is `190mb` to leave headroom under the instance limit; tune it with `--max-size`.
+
+If a **single file** or a **single data unit's XML** is larger than `--max-size` on its own, it cannot be placed in any part (a file is never split across archives) and the command errors — reduce the export scope for that unit or raise `--max-size` if the instance allows a larger archive.
+
+When you run a normal (non-`--split`) directory import and the assembled archive exceeds the limit, the command warns and recommends re-running with `--split`. `--split` cannot be combined with `--remote`, subset `PATHS`, or `--no-wait`.
+
 ---
 
 ## b2c job export