Experiment: create Studio sites from static artifacts

[chubes4]

Summary

• Adds an experimental studio create --from <source> CLI path for creating a new Studio site from a Static Site Importer source.
• Generates a temporary Blueprint that installs Static Site Importer into the new site and passes the source payload through SSI's import surface.
• Supports directories, individual files, ZIP archives, .fig files, URLs, and website artifact JSON by shaping the source as SSI expects.
• Adds a local Figma import handoff endpoint in the Studio app so a Figma plugin can post a source-style Figma payload directly to Studio without asking the user to run a shell command.
• Adapts the plugin's wordpress-studio/figma-source/v1 payload into SSI's generic Figma scenegraph request before import.
• Routes Figma scenegraph handoff payloads through Static_Site_Importer_Figma_Import::import() when SSI provides the Figma adapter, while keeping website artifact payload support for tests/debug.
• Keeps Studio responsible for site lifecycle/orchestration while SSI remains the source-to-theme import engine.
• Opens handoff-created sites through Studio's admin auto-login URL.
• Removes Static Site Importer after a successful import while keeping the generated theme and import result.

Why

This explores a generic Studio import primitive outside the AI loop: any producer can hand Studio an import source, and Studio can create a new local site from it. Static site directories, HTML exports, ZIPs, website artifacts, Figma exports, AI-generated outputs, and future source adapters can all target the same Studio create/import path.

The CLI remains the regression-friendly primitive. The Figma loopback endpoint is the product handoff layer: when Studio is running locally, a Figma plugin can send a source payload to Studio. Studio creates the site, starts it, and opens the new local site URL in the browser.

Current shape

studio create --from ./site-directory --name "Imported Site" --skip-browser
studio create --from ./index.html --name "Imported Site" --skip-browser
studio create --from ./site.zip --name "Imported Site" --skip-browser
studio create --from ./design.fig --name "Imported Site" --skip-browser
studio create --from ./artifact.json --name "Imported Site" --skip-browser
studio create --from https://example.com --name "Imported Site" --skip-browser

Optional for testing pinned SSI builds:

studio create --from ./site-directory --static-site-importer-url https://example.com/static-site-importer.zip

Figma plugin handoff shape:

POST http://127.0.0.1:48732/figma-to-wordpress/import
Content-Type: application/json

{
  "siteName": "Imported Figma Site",
  "source": {
    "schema": "wordpress-studio/figma-source/v1",
    "source": {
      "type": "figma",
      "metadata": {
        "fileKey": "...",
        "fileName": "Marketing site",
        "currentPage": { "id": "0:1", "name": "Landing" }
      },
      "exportedAt": "2026-01-01T00:00:00.000Z"
    },
    "intent": {
      "scope": "selected-nodes",
      "pageId": "0:1",
      "selectedNodeIds": ["1:2"]
    },
    "scenegraph": {
      "currentPage": {},
      "selectedNodes": []
    },
    "assets": [],
    "transform": {
      "target": "wordpress",
      "route": "static-site-importer/figma",
      "options": {}
    }
  }
}

Canonical website artifact payloads remain accepted for tests/debug:

{
  "siteName": "Imported Artifact Site",
  "artifact": {
    "schema": "blocks-engine/php-transformer/site-artifact/v1",
    "entrypoint": "website/index.html",
    "files": []
  }
}

Successful handoff response includes siteId, siteName, sitePath, and siteUrl.

Import engine lifecycle

• Studio installs Static Site Importer as temporary import tooling during site creation.
• Studio shapes the selected source into SSI's source payload contract.
• SSI resolves the source, imports it, and activates the generated theme.
• Figma plugin source payloads are adapted by Studio into SSI's generic Figma scenegraph request.
• Figma handoff scenegraph sources are delegated to SSI's Figma import adapter instead of being pre-resolved by Studio.
• After SSI reports a successful import, Studio deactivates and deletes the temporary SSI plugin.
• The generated theme and stored import result remain in the site.

End-to-end proof

Latest lifecycle rig run passed in Lab with a source matrix from the merged blocks-engine/fixtures/websites corpus:

• Run: ac9dfea0-482c-46e7-856d-4fc764c12ca5
• Command: homeboy bench --rig studio-artifact-import-lifecycle --scenario studio-artifact-import-lifecycle --iterations 1 --shared-state /tmp/studio-artifact-import-lifecycle --runner homeboy-lab --lab-only --json
• Metrics: source_count=2, success_rate=1, import_success=1, importer_removed=1, active_theme_present=1
• Sources: 2-onepager-coffee directory and 20-switchback-woocommerce-extra-hard.zip

The proof created brand-new Studio sites from import sources, confirmed the generated theme was active, confirmed the stored import result reported success, and confirmed SSI was no longer installed after import.

Testing

• npx vitest run apps/cli/commands/site/tests/create.test.ts
• npm -w wp-studio run typecheck
• npx eslint apps/cli/commands/site/create.ts apps/cli/commands/site/tests/create.test.ts apps/cli/lib/native-php/php-process.ts apps/cli/lib/native-php/blueprints.ts
• npx eslint apps/studio/src/lib/figma-import-handoff-server.ts apps/studio/src/index.ts
• npm run cli:build
• node apps/cli/dist/cli/main.mjs create --help
• npx vitest run apps/studio/src/lib/tests/figma-import-handoff-server.test.ts
• npx eslint apps/studio/src/lib/figma-import-handoff-server.ts apps/studio/src/lib/tests/figma-import-handoff-server.test.ts
• npm -w studio-app run typecheck

Notes

• Draft/experiment only.
• Studio should keep passing sources into SSI rather than growing importer logic of its own.
• This intentionally does not re-architect the Studio agent loop. The CLI import primitive can be used by AI later, but is not AI-owned.

AI assistance

• AI assistance: Yes
• Tool(s): openai/gpt-5.5 via OpenCode
• Used for: Exploring the architecture, drafting the CLI prototype, generalizing the source contract, adding focused tests, debugging the Blueprint/PHP bootstrap issue, adding the Figma loopback handoff, adapting plugin source payloads into SSI's generic Figma scenegraph request, routing Figma scenegraph handoff payloads through SSI's Figma import adapter, and running validation.