Reprint pull engine: design and engine-switch compatibility findings (STU-1815)

[gcsecsey]

Related issues

• Related to STU-1815
• Follow-up work depends on Agentic UI: Port selective sync #4377 (selective sync)

How AI was used in this PR

Claude explored the two pull paths, ran the compatibility testing described below against a real remote site, and drafted the design doc. I made the design decisions and reviewed the findings.

Proposed Changes

Design only so far — no code yet. This documents the agreed plan for STU-1815 and, more importantly, records compatibility testing that changed the shape of it.

The premise in STU-1815 is that "Studio uses the CLI pull command", but that only holds for the Agentic UI. The legacy renderer pulls over the WordPress.com REST API directly and never touches the CLI, so only the Agentic UI can swap engines.

The interesting finding is that switching engines on an existing site is not symmetric. A Reprint pull rewrites the site so every top-level entry is a symlink into ~/.studio/pulls/<siteId>/raw/. Pulling that site with the Jetpack engine afterwards merges the backup through those symlinks into the Reprint scratch, then fails on the database import and retries forever. Reprint-onto-Jetpack works fine.

So a single global beta flag isn't safe: flipping it off after a Reprint pull would break the site. The engine has to be derived per site from reprintOrigin, which the site record already carries, with a guard in pull refusing to run against a Reprint-shaped site.

Also worth noting: "just overwrite everything with a Jetpack pull" doesn't rescue this. That importer merges rather than replaces and never lays down core — and on a Reprint-shaped site, core is symlinks into the scratch.

Two unrelated bugs surfaced during testing and are called out in the doc for separate issues: a failed database import retries indefinitely, and the importer follows symlinks out of the site directory (unreachable via studio pull, but live for the Playground/Local/SQL/WXR/Wpress importers).

Testing Instructions

This PR only adds a document, so there is nothing to run. To reproduce the compatibility finding:

1. npm run cli:build
2. Create two sites: node apps/cli/dist/cli/main.mjs site create --path ~/Studio/flip-a --name flip-a --start=false and the same for flip-b.
3. On flip-a, pull with Reprint first, then with the legacy engine:

   STUDIO_ENABLE_PULL_REPRINT=true node apps/cli/dist/cli/main.mjs pull-reprint --path ~/Studio/flip-a --url <your-atomic-site>
   node apps/cli/dist/cli/main.mjs pull --path ~/Studio/flip-a --remote-site <site-id> --options all
   

   The second command fails with "Could not locate the SQLite integration plugin" and then loops indefinitely — it has to be killed. Check ~/.studio/pulls/<siteId>/raw/srv/htdocs/wp-content and note the freshly written Jetpack files.
4. On flip-b, do the same two pulls in the opposite order. Both succeed.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[gcsecsey]

Closing — this was committed prematurely. The design is still under discussion and there is no implementation yet.