Automattic / Automattic/studio
Converge Data Liberation site materialization on studio create --from
- Dominant language
- TypeScript
- Stars
- 517
- Forks
- 95
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 162
Description
## What
Converge Data Liberation's local static-site materialization path on the shared `studio create --from` import path proposed in [#3952](https://github.com/Automattic/studio/pull/3952).
Data Liberation should continue to own source-side work that benefits from its existing capabilities: platform-aware acquisition, browser-rendered HTML capture, asset localization, source diagnostics, screenshots, and optional visual evaluation. Once it has produced a portable static website directory, Studio should own site lifecycle and route that source through the shared Blocks Engine and Static Site Importer planning/materialization path.
The intended boundary is:
```text
Data Liberation
-> acquire/hydrate/localize source
-> portable static website directory + capture evidence
Studio create --from
-> provision site
-> normalize source for Blocks Engine
-> canonical WordPress site plan
-> Static Site Importer materialization
-> created Studio site
Data Liberation (optional)
-> visual comparison and repair evidence
```
This issue tracks the convergence and compatibility proof. It does not require redirecting existing `/liberate` behavior before the shared path proves equivalent.
## Why
Data Liberation currently contains deterministic local-directory abilities that both interpret source files and directly mutate a Studio WordPress site. That path provisions/reuses Studio, generates and installs themes, creates pages, writes media and options, configures the front page, and optionally performs comparison and repair.
Static Site Importer provides a second materialization path around the canonical Blocks Engine site-plan contract. Maintaining both paths duplicates destination concerns and makes Data Liberation responsible for acquisition, conversion, Studio provisioning, WordPress mutation, and verification at once.
Separating acquisition from destination materialization should:
- keep browser and source-specific concerns in Data Liberation;
- give Studio one CLI-facing import lifecycle for directories, archives, artifacts, and captured sites;
- give Blocks Engine one canonical conversion contract;
- give Static Site Importer one reference WordPress materialization path;
- reduce duplicate theme/page/media/settings mutation logic;
- make captures reusable without repeating remote acquisition;
- make phase failures and receipts easier to inspect and resume.
The architecture and handoff are feasible, but improved speed, reliability, and output equivalence remain hypotheses to verify before removing the current Data Liberation materializer.
## How
1. Expose a deterministic Data Liberation capture/export primitive that produces a portable static website directory with localized assets and bounded provenance/diagnostics.
2. Teach `studio create --from ` to identify the importable website root without treating screenshots, logs, or diagnostics as website files.
3. Normalize the portable directory into the existing self-contained Blocks Engine website-artifact contract rather than introducing a competing artifact format.
4. Compile and apply through the canonical Blocks Engine site-plan and Static Site Importer lifecycle.
5. Keep the current Data Liberation direct materializer available while both paths are compared from identical frozen source fixtures.
6. Move reusable source interpretation upstream only where the shared path demonstrates a concrete gap.
7. Retire duplicated Data Liberation provisioning and WordPress mutation responsibilities only after compatibility is demonstrated or differences are explicitly accepted.
## Acceptance criteria
Use identical, immutable source fixtures to compare the current Data Liberation direct path with the shared `studio create --from` path. The comparison must be repeatable and runnable headlessly with repository-native commands.
- Page, route, media, navigation, form, option, and front-page completeness are equivalent or intentionally improved.
- Internal links resolve and required assets are localized; unintended remote-asset leakage is reported.
- Desktop and mobile frontend output meet an agreed visual-parity threshold.
- Generated block markup is valid in the editor and preserves the intended editability contract.
- Native-block and fallback usage is equivalent or improved, with fallback reasons reported.
- Required runtime behavior is preserved or explicitly classified as unsupported.
- Repeated application is idempotent, and interruption/resume behavior is tested at phase boundaries.
- Failures produce actionable diagnostics without silently creating an incomplete site.
- Total and phase runtime, peak resources, and repeat-run success rate are recorded for both paths.
- Compatibility dimensions currently handled only by Data Liberation are identified before its direct materializer is removed.
- Existing `/liberate` behavior remains available until the shared path satisfies these gates.
## Related
- [#3952 Add studio create --from static source imports](https://github.com/Automattic/studio/pull/3952)
- [Architecture discussion on #3952](https://github.com/Automattic/studio/pull/3952#issuecomment-5172938564)
- [Static Site Importer](https://github.com/Automattic/static-site-importer)
- [Blocks Engine](https://github.com/Automattic/blocks-engine)
## AI assistance
- **Model/tool:** OpenAI gpt-5.6-sol via OpenCode
- **Used for:** Source-code analysis across Studio, Data Liberation, Blocks Engine, and Static Site Importer; architecture synthesis; acceptance-criteria drafting; and public-context review.
- Chris Huber reviewed and remains responsible for this issue.
Contributor guide
Research direction
Start at the `studio create --from ` entry point and the existing `/liberate` materializer, then trace their handoff to the Blocks Engine and Static Site Importer. Use identical frozen source fixtures and repository-native headless commands to compare both paths; done means the shared path meets the listed completeness, parity, idempotency, resume, diagnostics, and runtime gates without removing `/liberate`.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, typescript
- Domain
- backend, cli, desktop
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100