Check publish readiness

Every worked value below is SYNTHETIC / UNRUN; no action was called.

Check publish readiness, verification URLs, responsive viewports, and rollback action without changing the site.

Request

• Action: app_topolo_web.sites.publish.preflight
• Method and path: GET /api/studio/sites/{siteId}/publish-preflight
• Required permission: app_topolo_web.studio:read
• Input: {"siteId":"site_synth_01"}
• Additional input fields: false

How it behaves

Read-only publish readiness and URL preflight for one scoped site. The action does not publish or change site state. canPublish is true exactly when qualityReport.issues contains no error severity. The body includes the site ID, preview/public URLs, quality report, required viewport widths [390, 768, 1440, 2560], and rollbackActionId. A false result is still HTTP 200; the report identifies blockers.

Worked examples

SYNTHETIC / UNRUN — no error-severity quality issues

HTTP 200; response body (synthetic/unrun):

{
  "canPublish": true,
  "siteId": "site_synth_01",
  "previewUrl": "https://runtime.example.invalid/?preview=draft-preview-synth-01",
  "publicUrl": "https://northstar.example.invalid",
  "qualityReport": {
    "generatedAt": "2026-10-23T02:30:00.000Z",
    "score": 92,
    "issues": [
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "requiredViewports": [
    390,
    768,
    1440,
    2560
  ],
  "rollbackActionId": "app_topolo_web.sites.versions.restore"
}

SYNTHETIC / UNRUN — a launch-blocking hero issue

HTTP 200; response body (synthetic/unrun):

{
  "canPublish": false,
  "siteId": "site_synth_01",
  "previewUrl": "https://runtime.example.invalid/?preview=draft-preview-synth-01",
  "publicUrl": "https://northstar.example.invalid",
  "qualityReport": {
    "generatedAt": "2026-10-23T02:30:00.000Z",
    "score": 72,
    "issues": [
      {
        "id": "hero_action_missing",
        "severity": "error",
        "title": "Hero section has no primary action",
        "detail": "The landing experience should expose one clear next step from the first screen."
      },
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "requiredViewports": [
    390,
    768,
    1440,
    2560
  ],
  "rollbackActionId": "app_topolo_web.sites.versions.restore"
}

SYNTHETIC / UNRUN — site is missing or outside the selected workspace

HTTP 404; response body (synthetic/unrun):

{
  "error": "Site not found"
}

Errors and recovery

Missing or out-of-scope site returns 404 with localized siteNotFound text. Action descriptor also lists generic authentication, permission, input and dependency errors. If canPublish is false, resolve each error-severity quality issue, then request preflight again. This action does not prove a publish occurred or that visual checks passed.

Who should use this guide

For site owners deciding whether to proceed to the separate publish action. Typed guide is appropriate for gating workflows; branch on canPublish and issue severity, not HTTP status alone.

Provenance and change log

Pinned d9 source d9c75819abedaf71f9436a1d200015883a291072 (tree 186133adb5823723307184dcbd77acb1814317a1) plus the exact saved action descriptor in the current detailed catalog. The action metadata in the saved detailed catalog is bound by SHA-256 0d37dbcd6b71ee45f4e09d2a34dcb8331676dd2c0ea2184460400ec1abe688fc. Relevant implementation paths at revision d9c75819abedaf71f9436a1d200015883a291072: apps/api/src/routes/studio.ts:403-411, apps/api/src/repositories/store/sites.ts:1011-1023, apps/api/src/repositories/store/sites.ts:339-349, packages/render/src/site-quality.ts:329-349, packages/render/src/site-quality.ts:796-805. Current-source freshness beyond the saved d9/release association is UNKNOWN; this is not fresh production action readback.

Change log — 2026-10-23 — source-derived guide content: aligned method/path/permission and input to the saved current descriptor; added synthetic/unrun branch examples; documented source behavior and recovery; left missing/ambiguous envelopes and output schema gaps explicit.

Unresolved: The route-localized not-found text and provider-side reconciliation outcome are not verified by execution. Exact auth error envelopes are not claimed.