Skip to content

Declare the site's live preview (saas-parallel-baselining PB4) - #4

Merged
ruehowl merged 2 commits into
mainfrom
claude/declare-preview
Nov 4, 2026
Merged

ruehowl merged 2 commits into
mainfrom
claude/declare-preview

Conversation

@ruehowl

@ruehowl ruehowl commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

What

The baseline declares its live preview, so orun.work's Preview tab can show a coding session's dev server (saas-parallel-baselining PB4).

  • apps/web/component.yaml: spec.preview:
    preview:
      run:
      - sh
      - -c
      - pnpm install --frozen-lockfile --prefer-offline --filter "@app/web..." && (cd ../../packages/client && exec node_modules/.bin/tsup) && node scripts/generate.cjs && exec env NODE_OPTIONS="$NODE_OPTIONS --import urlpattern-polyfill" node_modules/.bin/next dev -H localhost -p 3000
      port: 3000
      path: /
      env:
        NODE_OPTIONS: --max-old-space-size=1024 --dns-result-order=ipv4first
        NEXT_TELEMETRY_DISABLED: '1'
  • intent.yaml: preview: {component: web}.
  • apps/web/next.config.ts: allowedDevOrigins: ['*.orun-preview.app', 'preview-gateway-stage.oruncloud.workers.dev']. The gateway gives the dev server a local Host but passes the browser's Origin through, and Next 16 refuses the hot reload's WebSocket from an unlisted origin (Unauthorized). Only next dev reads this setting; next build and the deployed Worker don't.
  • apps/web/next.config.ts, in experimental (next to optimizePackageImports), only when NODE_ENV is development: serverActions.allowedOrigins for the same two hosts. For the same reason Next 16 refuses every Server Action behind the gateway ("Invalid Server Actions request", 500). next build runs with NODE_ENV=production, so the deployed Worker keeps its same-origin check.
  • apps/web/lib/content-security-policy.ts: under next dev only (NODE_ENV === 'development'), the CSP leaves out frame-ancestors. The storefront sends frame-ancestors 'none' (or Makeswift's origin) on every page, which kept the dev server out of the Preview tab's frame, and the gateway can only append to a page's frame-ancestors, not loosen it. next build runs with NODE_ENV=production, so the deployed storefront's header is byte-for-byte the same.
  • .github/workflows/baseline.yml: orun v2.88.0 → v2.96.0 (all three jobs), the first release that reads spec.preview, so the placement test's orun validate checks the declaration; its comments say why. ci.yml (the site's own lane pin, v2.78.4) is unchanged.

Nothing about how the baseline builds or deploys changes.

Checked

From a clean clone, with orun v2.96.0, and through a local stand-in of the preview gateway (the dev server sees a local Host and the browser's own Origin; the page is framed from a foreign origin):

Check Result
orun validate passes
orun preview start --json ready in 14.2 s (warm pnpm store)
GET / 200, 12.8 KB, "Catalyst Store"
foreign Host + Origin straight to the dev server 200
through the gateway stand-in, framed frame 200, failed: FAILED net::ERR_ABORTED /?_rsc=7h47x, hot-reload socket connected
an edit reaches the frame hot update in 1.0s
memory dev server 1046 MB at its peak (page compiled, after an edit); the install peaks at 1203 MB
orun preview stop stops it; port freed

Notes

  • -H localhost, with --dns-result-order=ipv4first. The proxy rewrites / to /connect-store (and, with a store, routes by locale and channel). With next dev -H 127.0.0.1, Next normalizes 127.0.0.1 in the request's URL to localhost, so every rewrite looks external, and behind the gateway (which passes x-forwarded-proto: https) Next proxies it to https://localhost:3000 and fails (500, EPROTO). Bound to localhost, / answers 200 with and without x-forwarded-proto: https; ipv4first makes localhost resolve to 127.0.0.1 only, so the listener is still loopback IPv4 alone (/proc/net/tcp shows 0100007F:0BB8, nothing on tcp6, [::1]:3000 refused). The proxy's redirects come back relative (307 /), so they stay on the preview's host.
  • Before next dev, the preview builds packages/client (tsup, a few seconds; next.config.ts imports it, and its dist/ is not committed) and runs scripts/generate.cjs (the GraphQL types from the committed bigcommerce.graphql, offline), as the build and pnpm dev do. The proxies build URLPattern matchers at import; URLPattern is a global from Node 24 on, and the box runs Node 22, so the preview's next dev preloads urlpattern-polyfill (already the site's devDependency, the one vitest.setup.ts loads; it fills the global in only where it is missing). Without it next dev cannot load the proxy at all.
  • The preview is given no BigCommerce store (nothing secret reaches env), so / is the storefront's own "Connect your BigCommerce store" page and every other page redirects there — what a fresh deploy without a store serves. / compiles no Server Actions, so the action probe answered 404 for every origin; the allow-list is the same dev-only block as the other Next baselines'.
  • Contract tests (incl. wire), leak.test.sh, placement.test.sh (orun v2.96.0) and gen-component-docs.py --check pass locally; the edited .ts files are Prettier-clean with the app's settings. The /?_rsc request aborted in the frame is the router's fetch superseded by the hot update (net::ERR_ABORTED). Next 16.3's next dev writes apps/web/AGENTS.md and CLAUDE.md on startup; this PR leaves that alone.

Generated by Claude Code

orun.work's Preview tab shows a coding session's dev server, live from its
box: `orun preview` (orun v2.96.0) runs what a repository declares, and the
session keeps it running while it works.

- apps/web/component.yaml: spec.preview. It installs this app's packages
  only (--filter "@app/web..."), builds packages/client (the workspace
  package whose dist/ the site loads), writes the GraphQL types from the
  committed schema (scripts/generate.cjs, as `pnpm dev` does), then runs
  `next dev` alone on localhost:3000 with a 1 GiB heap cap; the tab opens
  /. --dns-result-order=ipv4first makes localhost 127.0.0.1 alone, and
  `localhost` keeps the proxy's rewrites in-process behind the gateway
  (Next normalizes 127.0.0.1 to localhost in a request's URL, and with
  -H 127.0.0.1 every rewrite looked external: a 500 under
  x-forwarded-proto: https). On a Node without the URLPattern global (it
  is Node 24's) `next dev` preloads the site's own urlpattern-polyfill,
  which the proxies' matchers need. It is given no BigCommerce store.
- intent.yaml: preview: {component: web}.
- apps/web/next.config.ts: allowedDevOrigins for the preview's hosts
  (*.orun-preview.app, preview-gateway-stage.oruncloud.workers.dev), and,
  only when NODE_ENV is development, experimental.serverActions
  .allowedOrigins for the same hosts. The gateway passes the browser's
  Origin through while `next dev` sees a local Host: Next 16 refuses the
  hot reload's WebSocket and every Server Action from an origin it is not
  told about. `next build` reads neither.
- apps/web/lib/content-security-policy.ts: `next dev` sends no
  frame-ancestors (NODE_ENV=development only). The storefront's
  `frame-ancestors 'none'` kept the dev server out of the Preview tab's
  frame, and the gateway can only add to it. `next build` runs with
  NODE_ENV=production, so the deployed storefront's CSP is unchanged.
- baseline.yml: orun v2.88.0 -> v2.96.0 (all three jobs), the first
  release that reads spec.preview, so the placement's `orun validate`
  checks it. ci.yml (the site's own lane pin) is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PcpNV6SjymJBPv3nNkC4z
`framing` was inferred as `{} | { frameAncestors: string[] }`, which
TypeScript widens to an optional `frameAncestors?: undefined` that
content-security-policy-builder's directive map refuses (TS2322 in the
site job's typecheck). Annotating it as Record<string, string[]> keeps the
same value: no frame-ancestors under `next dev`, the same header for every
build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PcpNV6SjymJBPv3nNkC4z
@ruehowl
ruehowl marked this pull request as ready for review November 4, 2026 21:37
@ruehowl
ruehowl merged commit cf6475e into main Nov 4, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants