An open source design system that's fully customizable and agent ready
TypeScript
ci: host PR Storybook previews with the docsite (#6506)
Cindy Zhangebaebc469a0c
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.jsindex 71480a023e..354da3755b 100644--- a/.github/scripts/generate-pr-comment.js+++ b/.github/scripts/generate-pr-comment.js@@ -193,7 +193,6 @@ if (storybookUrl) {storybookSection = `### 📚 Storybook Preview**${extLink('View Storybook for this PR', storybookUrl)}**-_GitHub Pages may take up to a minute to hydrate after deploy._`;}@@ -209,19 +208,22 @@ _GitHub Pages may take up to a minute to hydrate after deploy._`;}-// Explain each independently unavailable target. The reconciler only passes this-// state after validating the publisher's exact PR/head/source-run result.+// Storybook readiness follows Vercel; Sandbox still follows the source CI's+// trusted Pages publisher. Report their missing states independently.let previewAvailabilitySection = '';if (previewState) {const missing = [];- if (!storybookUrl) missing.push('Storybook');- if (!sandboxUrl) missing.push('Sandbox');- if (missing.length > 0) {- const reason =+ if (!storybookUrl)+ missing.push('Storybook is not ready on the exact-head Vercel preview.');+ if (!sandboxUrl) {+ missing.push(sourceConclusion === 'success'- ? `${missing.join(' and ')} ${missing.length === 1 ? 'was' : 'were'} not published for this CI run.`- : 'CI did not succeed, so no preview was published.';- previewAvailabilitySection = `> **Preview availability:** ${reason}\n\n`;+ ? 'Sandbox was not published for this CI run.'+ : `Sandbox is unavailable because CI concluded ${sourceConclusion || 'without a result'}.`,+ );+ }+ if (missing.length > 0) {+ previewAvailabilitySection = `> **Preview availability:** ${missing.join(' ')}\n\n`;}}diff --git a/.github/scripts/generate-pr-comment.test.mjs b/.github/scripts/generate-pr-comment.test.mjsindex b5073c1e27..79b9962052 100644--- a/.github/scripts/generate-pr-comment.test.mjs+++ b/.github/scripts/generate-pr-comment.test.mjs@@ -120,7 +120,7 @@ describe('generate-pr-comment preview availability', () => {'failure',]);- expect(stdout).toContain('CI did not succeed');+ expect(stdout).toContain('CI concluded failure');expect(stdout).not.toContain('View Storybook for this PR');expect(stdout).not.toContain('View Sandbox for this PR');});diff --git a/.github/scripts/lib/gh-pages-publisher.mjs b/.github/scripts/lib/gh-pages-publisher.mjsindex 407a4fb8ac..d9d363c1ce 100755--- a/.github/scripts/lib/gh-pages-publisher.mjs+++ b/.github/scripts/lib/gh-pages-publisher.mjs@@ -1336,9 +1336,8 @@ export async function publishManualVisualBaseline({}const PREVIEW_MANIFEST = '.astryx-preview.json';-const PREVIEW_RESERVED_ROOTS = new Set([PREVIEW_MANIFEST, 'sandbox', 'visual']);-function previewDirectory(value, name, {storybook = false} = {}) {+function previewDirectory(value, name) {if (!value) return null;const directory = path.resolve(value);if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {@@ -1348,13 +1347,6 @@ function previewDirectory(value, name, {storybook = false} = {}) {if (!fs.existsSync(index) || !fs.statSync(index).isFile()) {refuse(`${name} must contain index.html`);}- if (storybook) {- for (const reserved of PREVIEW_RESERVED_ROOTS) {- if (fs.existsSync(path.join(directory, reserved))) {- refuse(`${name} contains reserved path ${reserved}`);- }- }- }return directory;}@@ -1364,12 +1356,10 @@ function sha256(file) {function clearPreviewContents(destination) {fs.mkdirSync(destination, {recursive: true});- for (const entry of fs.readdirSync(destination, {withFileTypes: true})) {- if (entry.name === 'visual') continue;- fs.rmSync(path.join(destination, entry.name), {- recursive: true,- force: true,- });+ // Sandbox remains on Pages until its own migration. Keep Storybook and the+ // immutable visual evidence untouched when replacing Sandbox for this PR.+ for (const name of ['sandbox', PREVIEW_MANIFEST]) {+ fs.rmSync(path.join(destination, name), {recursive: true, force: true});}}@@ -1400,11 +1390,11 @@ export async function publishPrPreview({if (baseRepo !== repository) {refuse('preview base repository does not match publisher repository');}- const storybookDir = previewDirectory(storybook, '--storybook', {- storybook: true,- });+ if (storybook) {+ refuse('Storybook previews are hosted on Vercel, not gh-pages');+ }const sandboxDir = previewDirectory(sandbox, '--sandbox');- if (sourceConclusion !== 'success' && (storybookDir || sandboxDir)) {+ if (sourceConclusion !== 'success' && sandboxDir) {refuse('failed source CI cannot publish preview targets');}const identity = {@@ -1418,9 +1408,7 @@ export async function publishPrPreview({sourceRunAttempt,sourceConclusion,};- const storybookIndexSha256 = storybookDir- ? sha256(path.join(storybookDir, 'index.html'))- : null;+ const storybookIndexSha256 = null;const sandboxIndexSha256 = sandboxDir? sha256(path.join(sandboxDir, 'index.html')): null;@@ -1441,7 +1429,6 @@ export async function publishPrPreview({try {const destination = path.join(checkout, destinationRel);clearPreviewContents(destination);- if (storybookDir) copyContents(storybookDir, destination);if (sandboxDir) {const sandboxDestination = path.join(destination, 'sandbox');fs.mkdirSync(sandboxDestination, {recursive: true});@@ -1454,12 +1441,6 @@ export async function publishPrPreview({);}}- if (- storybookDir &&- sha256(path.join(destination, 'index.html')) !== storybookIndexSha256- ) {- refuse('published Storybook index does not match its source artifact');- }if (sandboxDir &&sha256(path.join(destination, 'sandbox', 'index.html')) !==diff --git a/.github/scripts/lib/gh-pages-publisher.test.mjs b/.github/scripts/lib/gh-pages-publisher.test.mjsindex 2e5e12e840..dd8f3f8b44 100644--- a/.github/scripts/lib/gh-pages-publisher.test.mjs+++ b/.github/scripts/lib/gh-pages-publisher.test.mjs@@ -1175,218 +1175,65 @@ describe('gh-pages publisher', () => {).toBe('old storybook');});- it('publishes PR previews without losing reports or visual state', async () => {+ it('publishes Sandbox only and preserves existing Storybook and visual bytes', async () => {const fx = fixture();- const storybook = path.join(fx.root, 'preview-storybook');const sandbox = path.join(fx.root, 'preview-sandbox');- writeFile(path.join(storybook, 'index.html'), 'new preview');writeFile(path.join(sandbox, 'index.html'), 'new sandbox');writeFile(path.join(sandbox, 'template-assets', 'ignored.txt'),- 'shared asset copy',+ 'shared asset',);-const result = await queuedPublish(fx, 940, 'pr-preview/123', () =>publishPrPreview({...context(fx, 940, 'pr-preview/123'),...previewIdentity(),- storybook,sandbox,}),);-const final = cloneRemote(fx.remote, fx.root);+ expect(fs.readFileSync(path.join(final, 'pr/123/index.html'), 'utf8')).toBe(+ 'preview',+ );expect(- fs.readFileSync(path.join(final, 'pr', '123', 'index.html'), 'utf8'),- ).toBe('new preview');- expect(- fs.readFileSync(- path.join(final, 'pr', '123', 'sandbox', 'index.html'),- 'utf8',- ),+ fs.readFileSync(path.join(final, 'pr/123/sandbox/index.html'), 'utf8'),).toBe('new sandbox');expect(- fs.existsSync(- path.join(final, 'pr', '123', 'sandbox', 'template-assets'),- ),+ fs.existsSync(path.join(final, 'pr/123/sandbox/template-assets')),).toBe(false);expect(- fs.readFileSync(- path.join(final, 'pr', '123', 'visual', 'evidence.json'),- 'utf8',- ),+ fs.readFileSync(path.join(final, 'pr/123/visual/evidence.json'), 'utf8'),).toBe('same-PR visual evidence');- const manifest = JSON.parse(- fs.readFileSync(- path.join(final, 'pr', '123', '.astryx-preview.json'),- 'utf8',- ),+ expect(fs.readFileSync(path.join(final, 'pr/124/index.html'), 'utf8')).toBe(+ 'closed preview',);- expect(manifest).toMatchObject({- repository: REPO,- pullRequest: {number: 123, headSha: HEAD},- sourceRun: {id: 333, attempt: 1},- targets: {- storybook: {available: true, path: 'pr/123/'},- sandbox: {available: true, path: 'pr/123/sandbox/'},- },+ expect(result.targets).toMatchObject({+ storybook: {available: false},+ sandbox: {available: true},});- expect(result).toMatchObject({- status: 'published',- pagesCommit: expect.stringMatching(/^[0-9a-f]{40}$/),- targets: {- storybook: {available: true},- sandbox: {available: true},- },- });- expect(- fs.readFileSync(- path.join(final, 'reports', 'vibe', 'index.html'),- 'utf8',- ),- ).toBe('vibe');- expect(- fs.existsSync(- path.join(final, 'visual-gate', 'baseline', 'manifest.json'),- ),- ).toBe(true);- expect(- fs.existsSync(- path.join(- final,- 'pr',- '42',- 'visual',- HEAD,- '123',- '1',- 'evidence.json',- ),- ),- ).toBe(true);- });-- it('rejects Storybook artifacts that collide with trusted visual evidence', async () => {- const fx = fixture();- const storybook = path.join(fx.root, 'colliding-storybook');- const sandbox = path.join(fx.root, 'colliding-sandbox');- writeFile(path.join(storybook, 'index.html'), 'new preview');- writeFile(- path.join(storybook, 'visual', 'evidence.json'),- 'untrusted evidence',+ const manifest = JSON.parse(+ fs.readFileSync(path.join(final, 'pr/123/.astryx-preview.json'), 'utf8'),);- writeFile(path.join(sandbox, 'index.html'), 'new sandbox');-- await expect(- queuedPublish(fx, 944, 'pr-preview/123', () =>- publishPrPreview({- ...context(fx, 944, 'pr-preview/123'),- ...previewIdentity(),- storybook,- sandbox,- }),- ),- ).rejects.toThrow(/reserved path visual/);-- const final = cloneRemote(fx.remote, fx.root);- expect(- fs.readFileSync(- path.join(final, 'pr', '123', 'visual', 'evidence.json'),- 'utf8',- ),- ).toBe('same-PR visual evidence');+ expect(manifest.targets).toMatchObject({+ storybook: {available: false},+ sandbox: {available: true},+ });});- it.each([- ['no deployment', false, false],- ['Storybook only', true, false],- ['Sandbox only', false, true],- ['both previews', true, true],- ])(- 'publishes independent target state: %s',- async (_label, hasStorybook, hasSandbox) => {- const fx = fixture();- const storybook = hasStorybook- ? path.join(fx.root, 'matrix-storybook')- : undefined;- const sandbox = hasSandbox- ? path.join(fx.root, 'matrix-sandbox')- : undefined;- if (storybook) writeFile(path.join(storybook, 'index.html'), 'storybook');- if (sandbox) writeFile(path.join(sandbox, 'index.html'), 'sandbox');- const resultFile = path.join(fx.root, 'preview-deployment.json');-- await queuedPublish(fx, 945, 'pr-preview/123', () =>- publishPrPreview({- ...context(fx, 945, 'pr-preview/123'),- ...previewIdentity(),- storybook,- sandbox,- resultFile,- }),- );-- const final = cloneRemote(fx.remote, fx.root);- expect(fs.existsSync(path.join(final, 'pr', '123', 'index.html'))).toBe(- hasStorybook,- );- expect(- fs.existsSync(path.join(final, 'pr', '123', 'sandbox', 'index.html')),- ).toBe(hasSandbox);- expect(- fs.readFileSync(- path.join(final, 'pr', '123', 'visual', 'evidence.json'),- 'utf8',- ),- ).toBe('same-PR visual evidence');- expect(fs.existsSync(path.join(final, 'pr', '124', 'index.html'))).toBe(- true,- );- const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));- expect(result.targets.storybook.available).toBe(hasStorybook);- expect(result.targets.sandbox.available).toBe(hasSandbox);- },- );-- it('refuses to mark a target available without its entry point', async () => {+ it('rejects attempts to republish Storybook onto Pages', async () => {const fx = fixture();- const storybook = path.join(fx.root, 'missing-index-storybook');- writeFile(path.join(storybook, 'assets', 'bundle.js'), 'bundle');-+ const storybook = path.join(fx.root, 'storybook');+ writeFile(path.join(storybook, 'index.html'), 'untrusted storybook');await expect(publishPrPreview({...context(fx, 946, 'pr-preview/123'),...previewIdentity(),storybook,}),- ).rejects.toThrow('--storybook must contain index.html');- });-- it('does not claim deployment when the gh-pages push fails', async () => {- const fx = fixture();- const storybook = path.join(fx.root, 'failed-storybook');- writeFile(path.join(storybook, 'index.html'), 'new preview');- const resultFile = path.join(fx.root, 'preview-deployment.json');-- await expect(- queuedPublish(fx, 946, 'pr-preview/123', () =>- publishPrPreview({- ...context(fx, 946, 'pr-preview/123'),- ...previewIdentity(),- storybook,- resultFile,- beforePush: () => {- throw new Error('simulated publisher failure');- },- }),- ),- ).rejects.toThrow('simulated publisher failure');-+ ).rejects.toThrow(/Storybook previews are hosted on Vercel/);const final = cloneRemote(fx.remote, fx.root);- expect(- fs.readFileSync(path.join(final, 'pr', '123', 'index.html'), 'utf8'),- ).toBe('preview');- expect(fs.existsSync(resultFile)).toBe(false);+ expect(fs.readFileSync(path.join(final, 'pr/123/index.html'), 'utf8')).toBe(+ 'preview',+ );});it('cleans stale previews without deleting visual evidence or live previews', async () => {diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjsindex a8bb4382a5..3665ecb05e 100644--- a/.github/scripts/lib/pr-preview.mjs+++ b/.github/scripts/lib/pr-preview.mjs@@ -6,9 +6,15 @@ import path from 'node:path';import process from 'node:process';import {fileURLToPath} from 'node:url';+import {resolveVercelPreview} from './vercel-preview.mjs';+export const PR_ANALYSIS_MARKER = '<!-- astryx-pr-analysis -->';export const PREVIEW_RESULT_VERSION = 1;+function headMarker(sha) {+ return `<!-- astryx-pr-head:${sha} -->`;+}+const FULL_SHA = /^[0-9a-f]{40}$/;const SHA256 = /^[0-9a-f]{64}$/;const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;@@ -440,14 +446,29 @@ function pagesURL(identity, targetPath) {return `https://${owner}.github.io/${repo}/${targetPath}`;}-function safeCurrentBody({identity, runUrl, message: overrideMessage}) {+function safeCurrentBody({+ identity,+ runUrl,+ message: overrideMessage,+ previewOrigin,+ sandboxPath,+}) {const conclusion = identity.sourceConclusion;const message =overrideMessage ??(conclusion === 'success'- ? 'The current CI run completed, but its trusted analysis is unavailable. Preview links are not shown.'- : `The current CI run concluded ${conclusion || 'without a result'}. Current analysis and preview links are unavailable.`);- return `## PR Analysis Report\n${PR_ANALYSIS_MARKER}\n\n> **Current run:** ${message}\n\n---\n\n<sub>Generated by PR Enrichment workflow | <a href="${runUrl}" target="_blank" rel="noopener noreferrer">View current CI run</a></sub>\n`;+ ? 'The current CI run completed, but its trusted analysis is unavailable.'+ : `The current CI run concluded ${conclusion || 'without a result'}. Current analysis is unavailable.`);+ const links = [+ previewOrigin &&+ `[View Storybook for this PR](${previewOrigin}/storybook/)`,+ sandboxPath &&+ `[View Sandbox for this PR](${pagesURL(identity, sandboxPath)})`,+ ].filter(Boolean);+ const previewMessage = links.length+ ? `\n\n${links.join(' · ')}`+ : '\n\nThe exact-head preview is not available yet.';+ return `## PR Analysis Report\n${PR_ANALYSIS_MARKER}\n${headMarker(identity.headSha)}\n\n> **Current run:** ${message}${previewMessage}\n\n---\n\n<sub>Generated by PR Enrichment workflow | <a href="${runUrl}" target="_blank" rel="noopener noreferrer">View current CI run</a></sub>\n`;}function readJSON(file) {@@ -473,7 +494,7 @@ function trustedDeployment({deploymentResultPath, identity, core}) {return validateDeploymentResult(readJSON(deploymentResultPath), identity);} catch (error) {core.warning(- `Ignoring untrusted or stale preview result: ${error.message}`,+ `Ignoring untrusted or stale Sandbox result: ${error.message}`,);return null;}@@ -502,6 +523,7 @@ export async function reconcilePrComment({visualReportPath = '',createIfMissing = true,fallbackMessage,+ lookupPreview = resolveVercelPreview,generator = GENERATOR,execute = execFileSync,}) {@@ -519,13 +541,25 @@ export async function reconcilePrComment({identity,core,});+ const previewOrigin =+ createIfMissing && !identity.draft+ ? await lookupPreview({+ github,+ owner,+ repo,+ prNumber: identity.prNumber,+ headSha: identity.headSha,+ })+ : null;const deployment = trustedDeployment({deploymentResultPath,identity,core,});- const storybook = deployment?.targets.storybook.available === true;- const sandbox = deployment?.targets.sandbox.available === true;+ const storybook = previewOrigin !== null;+ const sandbox =+ !identity.draft && deployment?.targets.sandbox.available === true;+ const sandboxPath = sandbox ? deployment.targets.sandbox.path : null;const comments = await allComments(github, owner, repo, identity.prNumber);const botComments = comments.filter(comment => comment.user?.type === 'Bot');const botComment =@@ -535,7 +569,7 @@ export async function reconcilePrComment({core.info(`No existing PR Analysis Report to reconcile on #${identity.prNumber}.`,);- return {action: 'none', body: null, identity, deployment};+ return {action: 'none', body: null, identity};}let body;@@ -568,15 +602,8 @@ export async function reconcilePrComment({: []),]: []),- ...(storybook- ? [- '--storybook-url',- pagesURL(identity, deployment.targets.storybook.path),- ]- : []),- ...(sandbox- ? ['--sandbox-url', pagesURL(identity, deployment.targets.sandbox.path)]- : []),+ ...(storybook ? ['--storybook-url', `${previewOrigin}/storybook/`] : []),+ ...(sandbox ? ['--sandbox-url', pagesURL(identity, sandboxPath)] : []),'--preview-state',previewState(storybook, sandbox),'--source-conclusion',@@ -587,15 +614,38 @@ export async function reconcilePrComment({String(identity.prNumber),];try {- body = execute(process.execPath, args, {encoding: 'utf8'});+ body = execute(process.execPath, args, {encoding: 'utf8'}).replace(+ PR_ANALYSIS_MARKER,+ `${PR_ANALYSIS_MARKER}\n${headMarker(identity.headSha)}`,+ );} catch (error) {core.warning(`Could not render current analysis: ${error.message}`);- body = safeCurrentBody({identity, runUrl, message: fallbackMessage});+ body = safeCurrentBody({+ identity,+ runUrl,+ message: fallbackMessage,+ previewOrigin,+ sandboxPath,+ });}} else {- body = safeCurrentBody({identity, runUrl, message: fallbackMessage});+ body = safeCurrentBody({+ identity,+ runUrl,+ message: fallbackMessage,+ previewOrigin,+ sandboxPath,+ });}+ // Vercel readiness can take minutes after the source run finishes. Check the+ // current PR and CI attempt again before changing any comment.+ await confirmSourceRunIdentity({+ github,+ owner,+ repo,+ expected: expectedIdentity,+ });if (botComment) {await github.rest.issues.updateComment({owner,@@ -604,7 +654,7 @@ export async function reconcilePrComment({body,});core.info(`Updated PR Analysis Report on #${identity.prNumber}.`);- return {action: 'updated', body, identity, deployment};+ return {action: 'updated', body, identity};}await github.rest.issues.createComment({@@ -614,5 +664,89 @@ export async function reconcilePrComment({body,});core.info(`Posted PR Analysis Report on #${identity.prNumber}.`);- return {action: 'created', body, identity, deployment};+ return {action: 'created', body, identity};+}++export async function reconcileEarlyPreviewComment({+ github,+ owner,+ repo,+ prNumber,+ headSha,+ origin,+ lookupPreview = resolveVercelPreview,+}) {+ const currentOrigin = await lookupPreview({+ github,+ owner,+ repo,+ prNumber,+ headSha,+ waitMs: 0,+ });+ if (currentOrigin !== origin) return {action: 'none'};++ const comments = await allComments(github, owner, repo, prNumber);+ const existing = comments.find(+ comment =>+ comment.user?.type === 'Bot' &&+ comment.body?.includes(PR_ANALYSIS_MARKER),+ );+ const links = `[View Storybook for this PR](${origin}/storybook/)`;+ const marker = headMarker(headSha);+ let body = `## PR Analysis Report\n${PR_ANALYSIS_MARKER}\n${marker}\n\n> **Storybook ready:** Built with this PR's docsite. Sandbox and CI evidence will be added when available.\n\n${links}\n`;+ if (existing?.body.includes(marker)) {+ if (existing.body.includes(`${origin}/storybook/`)) {+ return {action: 'unchanged'};+ }+ const oldOrigins = new Set(+ existing.body.match(+ /https:\/\/astryx-[a-z0-9]{9}-fbopensource\.vercel\.app/g,+ ) ?? [],+ );+ if (+ oldOrigins.size === 1 &&+ existing.body.includes('View Storybook for this PR')+ ) {+ // A same-head Vercel redeploy changes only the deployment origin. Keep+ // the already-enriched CI, a11y, and canonical visual evidence intact.+ body = existing.body.replaceAll([...oldOrigins][0], origin);+ } else if (!existing.body.includes('View Storybook for this PR')) {+ // CI may finish before Vercel. Add the now-ready links without discarding+ // current-head analysis or immutable visual evidence from that report.+ body = existing.body+ .replace(/^> \*\*Preview availability:\*\*[^\n]*\n\n/m, '')+ .replace('The exact-head preview is not available yet.', '')+ .replace(marker, `${marker}\n\n${links}`);+ }+ }++ const {data: current} = await github.rest.pulls.get({+ owner,+ repo,+ pull_number: prNumber,+ });+ if (+ current.state !== 'open' ||+ current.draft ||+ current.head?.sha !== headSha+ ) {+ return {action: 'none'};+ }+ if (existing) {+ await github.rest.issues.updateComment({+ owner,+ repo,+ comment_id: existing.id,+ body,+ });+ return {action: 'updated', body};+ }+ await github.rest.issues.createComment({+ owner,+ repo,+ issue_number: prNumber,+ body,+ });+ return {action: 'created', body};}diff --git a/.github/scripts/lib/pr-preview.test.mjs b/.github/scripts/lib/pr-preview.test.mjsindex 00ee450a96..938d8fc77e 100644--- a/.github/scripts/lib/pr-preview.test.mjs+++ b/.github/scripts/lib/pr-preview.test.mjs@@ -12,6 +12,7 @@ import {PR_ANALYSIS_MARKER,createPublishedDeploymentResult,createUnavailableDeploymentResult,+ reconcileEarlyPreviewComment,reconcilePrComment,resolveWorkflowRunPullRequest,validateAnalysisMetadata,@@ -22,6 +23,7 @@ const HEAD = 'a'.repeat(40);const BASE = 'b'.repeat(40);const PAGES = 'c'.repeat(40);const INDEX = 'd'.repeat(64);+const VERCEL_ORIGIN = 'https://astryx-3s4xgbci4-fbopensource.vercel.app';const ROOT = path.resolve(import.meta.dirname, '../../..');const REQUIRE = createRequire(import.meta.url);const ASYNC_FUNCTION = Object.getPrototypeOf(async function () {}).constructor;@@ -109,6 +111,21 @@ function githubFixture({value = identity(), comments = []} = {}) {get: vi.fn(async () => ({data: pull(value)})),list: vi.fn(async () => ({data: [pull(value)]})),},+ repos: {+ listDeployments: vi.fn(async () => ({+ data: [+ {+ id: 11,+ sha: value.headSha,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ },+ ],+ })),+ listDeploymentStatuses: vi.fn(async () => ({+ data: [{state: 'success', environment_url: VERCEL_ORIGIN}],+ })),+ },issues: {listComments: vi.fn(async ({issue_number}) => {state.listedIssues.push(issue_number);@@ -181,7 +198,7 @@ function fixture(value = identity(), {analysis = true, deployment} = {}) {return paths;}-function published(value, available = ['storybook', 'sandbox']) {+function published(value, available = ['sandbox']) {return createPublishedDeploymentResult(value, {storybookIndexSha256: available.includes('storybook') ? INDEX : null,sandboxIndexSha256: available.includes('sandbox') ? INDEX : null,@@ -192,6 +209,7 @@ function published(value, available = ['storybook', 'sandbox']) {async function reconcile({value = identity(),deployment,+ previewAvailable = false,analysis = true,comments = [],githubFixtureValue = value,@@ -217,6 +235,7 @@ async function reconcile({metadataPath: paths.metadata,a11yPath: paths.a11y,deploymentResultPath: paths.deployment,+ lookupPreview: async () => (previewAvailable ? VERCEL_ORIGIN : null),visualPath: paths.visual,createIfMissing,fallbackMessage,@@ -380,14 +399,17 @@ describe('trusted PR preview identity', () => {.map(([name]) => name);expect(writeCapableJobs).toEqual([+ 'preview-comment','spec-only-reconcile','deploy-preview','comment',]);for (const name of writeCapableJobs) {- expect(PR_COMMENT_WORKFLOW.jobs[name].if, name).toContain(- "needs.resolve.outputs.valid == 'true'",- );+ const expected =+ name === 'preview-comment'+ ? "needs.resolve-preview.outputs.valid == 'true'"+ : "needs.resolve.outputs.valid == 'true'";+ expect(PR_COMMENT_WORKFLOW.jobs[name].if, name).toContain(expected);}});@@ -481,52 +503,77 @@ describe('analysis metadata compatibility', () => {describe('PR comment preview reconciliation', () => {it.each([- ['no deployment', undefined, false, false],- ['Storybook only', published(identity(), ['storybook']), true, false],- ['Sandbox only', published(identity(), ['sandbox']), false, true],+ ['neither ready', undefined, false, false],+ ['Vercel Storybook only', undefined, true, false],+ ['Pages Sandbox only', published(identity()), false, true],+ ['both independent targets', published(identity()), true, true],[- 'both previews',- published(identity(), ['storybook', 'sandbox']),- true,- true,+ 'obsolete Pages Storybook proof',+ published(identity(), ['storybook']),+ false,+ false,],[- 'deployment failure',+ 'Pages failure with ready Storybook',createUnavailableDeploymentResult(identity(), 'publisher-failed'),- false,+ true,false,],])(- 'renders the behavioral availability matrix: %s',- async (_label, deployment, hasStorybook, hasSandbox) => {- const {result} = await reconcile({deployment});-+ 'shows only validated current targets: %s',+ async (_label, deployment, storybookReady, sandboxReady) => {+ const {result} = await reconcile({+ deployment,+ previewAvailable: storybookReady,+ });expect(result.body.includes('View Storybook for this PR')).toBe(- hasStorybook,+ storybookReady,+ );+ expect(result.body.includes('View Sandbox for this PR')).toBe(+ sandboxReady,);- expect(result.body.includes('View Sandbox for this PR')).toBe(hasSandbox);expect(result.body.includes('> **Preview availability:**')).toBe(- !hasStorybook || !hasSandbox,+ !storybookReady || !sandboxReady,);+ if (storybookReady)+ expect(result.body).toContain(`${VERCEL_ORIGIN}/storybook/`);+ if (sandboxReady)+ expect(result.body).toContain(+ 'https://facebook.github.io/astryx/pr/5697/sandbox/',+ );+ expect(result.body).not.toContain(+ 'https://facebook.github.io/astryx/pr/5697/</a>',+ );+ expect(result.body).not.toContain(`${VERCEL_ORIGIN}/sandbox/`);},);it('keeps current trustworthy analysis when source CI fails', async () => {const value = identity({sourceConclusion: 'failure'});- const deployment = createUnavailableDeploymentResult(- value,- 'source-failed',- );+ const deployment = {status: 'unavailable', reason: 'source-failed'};const {result} = await reconcile({value, deployment});expect(result.body).toContain('Modified Components');expect(result.body).toContain('Card');- expect(result.body).toContain('CI did not succeed');+ expect(result.body).toContain('CI concluded failure');expect(result.body).not.toContain('View Storybook for this PR');expect(result.body).not.toContain('View Sandbox for this PR');});+ it('shows the exact Vercel preview even when unrelated CI analysis fails', async () => {+ const value = identity({sourceConclusion: 'failure'});+ const {result} = await reconcile({+ value,+ analysis: false,+ previewAvailable: true,+ });+ expect(result.body).toContain('concluded failure');+ expect(result.body).toContain(`${VERCEL_ORIGIN}/storybook/`);+ expect(result.body).not.toContain('View Sandbox for this PR');+ expect(result.body).not.toContain(`${VERCEL_ORIGIN}/sandbox/`);+ });+it('replaces a stale linked comment when failed CI has no analysis artifact', async () => {const value = identity({sourceConclusion: 'failure'});const stale = {@@ -595,7 +642,10 @@ describe('PR comment preview reconciliation', () => {});expect(result.body).toContain('trusted analysis is unavailable');- expect(result.body).not.toContain('/pr/5697/');+ expect(result.body).toContain(+ 'https://facebook.github.io/astryx/pr/5697/sandbox/',+ );+ expect(result.body).not.toContain('View Storybook for this PR');expect(core.warning).toHaveBeenCalledWith(expect.stringContaining('Could not render current analysis'),);@@ -660,17 +710,12 @@ describe('PR comment preview reconciliation', () => {['wrong head', {headSha: 'e'.repeat(40)}],['wrong repository', {headRepository: 'someone/astryx'}],])(- 'fails closed for a deployment result with the %s',+ 'never treats an old Pages result with the %s as Vercel preview proof',async (_label, overrides) => {const deployment = published(identity(overrides));-- const {result, core} = await reconcile({deployment});-+ const {result} = await reconcile({deployment, previewAvailable: false});expect(result.body).not.toContain('View Storybook for this PR');expect(result.body).not.toContain('View Sandbox for this PR');- expect(core.warning).toHaveBeenCalledWith(- expect.stringContaining('Ignoring untrusted or stale preview result'),- );},);@@ -701,6 +746,34 @@ describe('PR comment preview reconciliation', () => {expect(state.listedIssues).toHaveLength(0);});+ it('refuses a head push that happens during Vercel readiness before writing a comment', async () => {+ const expected = identity();+ const current = identity({headSha: 'f'.repeat(40)});+ const paths = fixture(expected);+ const {github, state} = githubFixture({value: expected});+ await expect(+ reconcilePrComment({+ github,+ core: {info: vi.fn(), warning: vi.fn()},+ context: {+ repo: {owner: 'facebook', repo: 'astryx'},+ serverUrl: 'https://github.com',+ },+ expectedIdentity: expected,+ analysisPath: paths.analysis,+ metadataPath: paths.metadata,+ a11yPath: paths.a11y,+ visualPath: paths.visual,+ lookupPreview: async () => {+ github.rest.pulls.get.mockResolvedValue({data: pull(current)});+ return VERCEL_ORIGIN;+ },+ }),+ ).rejects.toThrow(/head does not match source run/);+ expect(state.created).toHaveLength(0);+ expect(state.updated).toHaveLength(0);+ });+it('does not emit links for dispatch without a PR-backed source run', async () => {const value = identity();const paths = fixture(value, {deployment: published(value)});@@ -734,15 +807,145 @@ describe('PR comment preview reconciliation', () => {const {result, state} = await reconcile({value,deployment: published(value),+ previewAvailable: true,});expect(result.action).toBe('created');expect(result.body).toContain(PR_ANALYSIS_MARKER);- expect(result.body).toContain('https://facebook.github.io/astryx/pr/5697/');+ expect(result.body).toContain(`${VERCEL_ORIGIN}/storybook/`);expect(result.body).toContain('https://facebook.github.io/astryx/pr/5697/sandbox/',);expect(state.created[0].issue_number).toBe(5697);expect(state.listedIssues).toEqual([5697]);});++ it('posts preview links before CI and later enriches the same report', async () => {+ const value = identity();+ const paths = fixture(value, {deployment: published(value)});+ const {github, state} = githubFixture({value});+ const early = () =>+ reconcileEarlyPreviewComment({+ github,+ owner: 'facebook',+ repo: 'astryx',+ prNumber: value.prNumber,+ headSha: value.headSha,+ origin: VERCEL_ORIGIN,+ lookupPreview: async () => VERCEL_ORIGIN,+ });+ expect((await early()).action).toBe('created');+ expect(state.comments[0].body).toContain(`${VERCEL_ORIGIN}/storybook/`);+ expect(state.comments[0].body).not.toContain('View Sandbox for this PR');+ expect(state.comments[0].body).not.toContain('Modified Components');+ expect((await early()).action).toBe('unchanged');+ expect(state.created).toHaveLength(1);++ const enriched = await reconcilePrComment({+ github,+ core: {info: vi.fn(), warning: vi.fn()},+ context: {+ repo: {owner: 'facebook', repo: 'astryx'},+ serverUrl: 'https://github.com',+ },+ expectedIdentity: value,+ analysisPath: paths.analysis,+ metadataPath: paths.metadata,+ a11yPath: paths.a11y,+ deploymentResultPath: paths.deployment,+ visualPath: paths.visual,+ lookupPreview: async () => VERCEL_ORIGIN,+ });+ expect(enriched.action).toBe('updated');+ expect(state.comments).toHaveLength(1);+ expect(state.comments[0].body).toContain('Modified Components');+ expect(state.comments[0].body).toContain(`${VERCEL_ORIGIN}/storybook/`);+ expect(state.comments[0].body).toContain(+ 'https://facebook.github.io/astryx/pr/5697/sandbox/',+ );+ });++ it('adds a late preview without discarding same-head CI and visual evidence', async () => {+ const value = identity();+ const {result, github, state} = await reconcile({+ value,+ deployment: published(value),+ previewAvailable: false,+ });+ expect(result.body).toContain('Modified Components');+ expect(result.body).toContain('Preview availability');+ const early = await reconcileEarlyPreviewComment({+ github,+ owner: 'facebook',+ repo: 'astryx',+ prNumber: value.prNumber,+ headSha: value.headSha,+ origin: VERCEL_ORIGIN,+ lookupPreview: async () => VERCEL_ORIGIN,+ });+ expect(early.action).toBe('updated');+ expect(state.comments[0].body).toContain('Modified Components');+ expect(state.comments[0].body).not.toContain('Preview availability');+ expect(state.comments[0].body).toContain(`${VERCEL_ORIGIN}/storybook/`);+ expect(state.comments[0].body).toContain(+ 'https://facebook.github.io/astryx/pr/5697/sandbox/',+ );+ });++ it('refreshes a same-head redeployment without losing CI, a11y, or visual evidence', async () => {+ const value = identity();+ const {github, state} = await reconcile({+ value,+ deployment: published(value),+ previewAvailable: true,+ });+ const prior = state.comments[0].body;+ const visualEvidence =+ '[Visual evidence](https://facebook.github.io/astryx/pr/5697/visual/example/)';+ state.comments[0].body += `\n${visualEvidence}`;+ const nextOrigin = 'https://astryx-atz4b1yim-fbopensource.vercel.app';++ const result = await reconcileEarlyPreviewComment({+ github,+ owner: 'facebook',+ repo: 'astryx',+ prNumber: value.prNumber,+ headSha: value.headSha,+ origin: nextOrigin,+ lookupPreview: async () => nextOrigin,+ });+ expect(result.action).toBe('updated');+ expect(state.comments).toHaveLength(1);+ expect(state.comments[0].body).toContain('Modified Components');+ expect(state.comments[0].body).toContain('Accessibility Audit');+ expect(state.comments[0].body).toContain(visualEvidence);+ expect(state.comments[0].body).toContain(`${nextOrigin}/storybook/`);+ expect(state.comments[0].body).toContain(+ 'https://facebook.github.io/astryx/pr/5697/sandbox/',+ );+ expect(state.comments[0].body).not.toContain(`${nextOrigin}/sandbox/`);+ expect(state.comments[0].body).not.toContain(VERCEL_ORIGIN);+ expect(prior).toContain(VERCEL_ORIGIN);+ });++ it('refuses an early comment when the deployment head becomes stale or draft', async () => {+ for (const value of [+ identity({headSha: 'f'.repeat(40)}),+ identity({draft: true}),+ ]) {+ const {github, state} = githubFixture({value});+ const result = await reconcileEarlyPreviewComment({+ github,+ owner: 'facebook',+ repo: 'astryx',+ prNumber: 5697,+ headSha: HEAD,+ origin: VERCEL_ORIGIN,+ lookupPreview: async () => VERCEL_ORIGIN,+ });+ expect(result.action).toBe('none');+ expect(state.created).toHaveLength(0);+ expect(state.updated).toHaveLength(0);+ }+ });});diff --git a/.github/scripts/lib/vercel-preview.mjs b/.github/scripts/lib/vercel-preview.mjsnew file mode 100644index 0000000000..2730c1bd22--- /dev/null+++ b/.github/scripts/lib/vercel-preview.mjs@@ -0,0 +1,144 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Resolve the docsite deployment for an exact pull-request head.+ * @input Trusted PR identity and GitHub's Vercel deployment/status records.+ * @output A validated deployment origin, or null if this head has no ready preview.+ * @position Trusted PR comment; never falls back to a branch or older PR head.+ */++const VERCEL_CREATOR = 'vercel[bot]';+const PREVIEW_ENVIRONMENT = 'Preview';++export function previewOrigin(deployment, status, headSha) {+ if (+ deployment?.sha !== headSha ||+ deployment.environment !== PREVIEW_ENVIRONMENT ||+ deployment.creator?.login !== VERCEL_CREATOR ||+ status?.state !== 'success'+ ) {+ return null;+ }+ try {+ const url = new URL(status.environment_url);+ if (+ url.protocol !== 'https:' ||+ url.username ||+ url.password ||+ !/^astryx-[a-z0-9]{9}-fbopensource\.vercel\.app$/.test(url.hostname) ||+ (url.pathname !== '/' && url.pathname !== '') ||+ url.search ||+ url.hash+ ) {+ return null;+ }+ return url.origin;+ } catch {+ return null;+ }+}++export async function resolveVercelDeploymentEvent({+ github,+ owner,+ repo,+ deployment,+ status,+}) {+ const origin = previewOrigin(deployment, status, deployment?.sha);+ if (!origin) return null;++ // GitHub's commit→PR association omits fork-only heads. The open-PR list+ // includes both forks and same-repo heads, so bind an exact, unique match.+ const pulls = await github.paginate(github.rest.pulls.list, {+ owner,+ repo,+ state: 'open',+ per_page: 100,+ });+ const matches = pulls.filter(+ pull =>+ pull.state === 'open' &&+ !pull.draft &&+ pull.head?.sha === deployment.sha &&+ pull.base?.repo?.full_name === `${owner}/${repo}`,+ );+ if (matches.length !== 1) return null;+ const prNumber = matches[0].number;+ const currentOrigin = await resolveVercelPreview({+ github,+ owner,+ repo,+ prNumber,+ headSha: deployment.sha,+ waitMs: 0,+ });+ if (currentOrigin !== origin) return null;+ return {prNumber, headSha: deployment.sha, origin};+}++export async function resolveVercelPreview({+ github,+ owner,+ repo,+ prNumber,+ headSha,+ waitMs = 5 * 60 * 1000,+ pollMs = 10000,+ now = Date.now,+ sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),+}) {+ const deadline = now() + waitMs;+ while (true) {+ const {data: pull} = await github.rest.pulls.get({+ owner,+ repo,+ pull_number: prNumber,+ });+ if (pull.state !== 'open' || pull.draft || pull.head?.sha !== headSha) {+ return null;+ }+ const {data: deployments} = await github.rest.repos.listDeployments({+ owner,+ repo,+ sha: headSha,+ environment: PREVIEW_ENVIRONMENT,+ per_page: 100,+ });+ const latest = deployments+ .filter(+ deployment =>+ deployment.sha === headSha &&+ deployment.environment === PREVIEW_ENVIRONMENT &&+ deployment.creator?.login === VERCEL_CREATOR,+ )+ .sort((a, b) => b.id - a.id)[0];+ if (latest) {+ const {data: statuses} = await github.rest.repos.listDeploymentStatuses({+ owner,+ repo,+ deployment_id: latest.id,+ per_page: 1,+ });+ const origin = previewOrigin(latest, statuses[0], headSha);+ if (origin) {+ // A head push or close during the status request must not gain links.+ const {data: current} = await github.rest.pulls.get({+ owner,+ repo,+ pull_number: prNumber,+ });+ if (+ current.state === 'open' &&+ !current.draft &&+ current.head?.sha === headSha+ ) {+ return origin;+ }+ return null;+ }+ }+ if (now() >= deadline) return null;+ await sleep(Math.min(pollMs, deadline - now()));+ }+}diff --git a/.github/scripts/lib/vercel-preview.test.mjs b/.github/scripts/lib/vercel-preview.test.mjsnew file mode 100644index 0000000000..e6f697d682--- /dev/null+++ b/.github/scripts/lib/vercel-preview.test.mjs@@ -0,0 +1,281 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it, vi} from 'vitest';++import {+ previewOrigin,+ resolveVercelDeploymentEvent,+ resolveVercelPreview,+} from './vercel-preview.mjs';++const SHA = 'a'.repeat(40);+const OLD_SHA = 'b'.repeat(40);+const ORIGIN = 'https://astryx-3s4xgbci4-fbopensource.vercel.app';++function fixture({+ head = SHA,+ draft = false,+ state = 'open',+ deployments,+ statuses,+ candidates = [+ {+ number: 123,+ state: 'open',+ draft: false,+ head: {sha: SHA, repo: {full_name: 'contributor/astryx'}},+ base: {repo: {full_name: 'facebook/astryx'}},+ },+ ],+} = {}) {+ const github = {+ rest: {+ pulls: {+ get: vi.fn(async () => ({data: {state, draft, head: {sha: head}}})),+ list: vi.fn(async () => ({data: candidates})),+ },+ repos: {+ listDeployments: vi.fn(async () => ({+ data: deployments ?? [+ {+ id: 7,+ sha: SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ },+ ],+ })),+ listDeploymentStatuses: vi.fn(async () => ({+ data: statuses ?? [{state: 'success', environment_url: ORIGIN}],+ })),+ },+ },+ paginate: vi.fn(async (method, request) => (await method(request)).data),+ };+ return github;+}++function resolve(github, options = {}) {+ return resolveVercelPreview({+ github,+ owner: 'facebook',+ repo: 'astryx',+ prNumber: 123,+ headSha: SHA,+ waitMs: 0,+ ...options,+ });+}++describe('exact-head Vercel preview', () => {+ it('only accepts a successful Vercel Preview deployment for the exact SHA', () => {+ const deployment = {+ sha: SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ };+ const status = {state: 'success', environment_url: ORIGIN};+ expect(previewOrigin(deployment, status, SHA)).toBe(ORIGIN);+ expect(+ previewOrigin(+ deployment,+ {+ ...status,+ environment_url: 'https://astryx-git-main-fbopensource.vercel.app',+ },+ SHA,+ ),+ ).toBeNull();+ expect(+ previewOrigin({...deployment, sha: OLD_SHA}, status, SHA),+ ).toBeNull();+ expect(+ previewOrigin({...deployment, environment: 'canary'}, status, SHA),+ ).toBeNull();+ expect(+ previewOrigin({...deployment, creator: {login: 'attacker'}}, status, SHA),+ ).toBeNull();+ expect(+ previewOrigin(deployment, {...status, state: 'pending'}, SHA),+ ).toBeNull();+ expect(+ previewOrigin(+ deployment,+ {...status, environment_url: 'https://evil.example/'},+ SHA,+ ),+ ).toBeNull();+ expect(+ previewOrigin(+ deployment,+ {...status, environment_url: `${ORIGIN}.evil.example`},+ SHA,+ ),+ ).toBeNull();+ expect(+ previewOrigin(+ deployment,+ {...status, environment_url: `${ORIGIN}/other`},+ SHA,+ ),+ ).toBeNull();+ });++ it('returns only the exact-head deployment origin and checks the head twice', async () => {+ const github = fixture();+ expect(await resolve(github)).toBe(ORIGIN);+ expect(github.rest.repos.listDeployments).toHaveBeenCalledWith({+ owner: 'facebook',+ repo: 'astryx',+ sha: SHA,+ environment: 'Preview',+ per_page: 100,+ });+ expect(github.rest.pulls.get).toHaveBeenCalledTimes(2);+ });++ it('refuses old-head, draft, and closed PRs without querying deployments', async () => {+ for (const options of [{head: OLD_SHA}, {draft: true}, {state: 'closed'}]) {+ const github = fixture(options);+ expect(await resolve(github)).toBeNull();+ expect(github.rest.repos.listDeployments).not.toHaveBeenCalled();+ }+ });++ it('does not reuse an older head or an older successful deployment while the newest deploy is pending', async () => {+ const old = {+ id: 6,+ sha: OLD_SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ };+ const current = {+ id: 8,+ sha: SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ };+ const github = fixture({+ deployments: [old, current],+ statuses: [{state: 'pending', environment_url: ORIGIN}],+ });+ expect(await resolve(github)).toBeNull();+ expect(github.rest.repos.listDeploymentStatuses).toHaveBeenCalledWith({+ owner: 'facebook',+ repo: 'astryx',+ deployment_id: 8,+ per_page: 1,+ });+ });++ it('waits for readiness within a bounded window and stops on a new head', async () => {+ const github = fixture({statuses: [{state: 'pending'}]});+ let time = 0;+ const sleep = vi.fn(async ms => {+ time += ms;+ github.rest.repos.listDeploymentStatuses.mockResolvedValue({+ data: [{state: 'success', environment_url: ORIGIN}],+ });+ });+ expect(+ await resolve(github, {waitMs: 20, pollMs: 10, now: () => time, sleep}),+ ).toBe(ORIGIN);+ expect(sleep).toHaveBeenCalledTimes(1);++ github.rest.pulls.get+ .mockResolvedValueOnce({+ data: {state: 'open', draft: false, head: {sha: SHA}},+ })+ .mockResolvedValueOnce({+ data: {state: 'open', draft: false, head: {sha: OLD_SHA}},+ });+ expect(await resolve(github)).toBeNull();+ });++ it('resolves fork and same-repository deployment events without source CI', async () => {+ const deployment = {+ id: 7,+ sha: SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ };+ const status = {state: 'success', environment_url: ORIGIN};+ for (const headRepository of ['contributor/astryx', 'facebook/astryx']) {+ const github = fixture({+ candidates: [+ {+ number: 123,+ state: 'open',+ draft: false,+ head: {sha: SHA, repo: {full_name: headRepository}},+ base: {repo: {full_name: 'facebook/astryx'}},+ },+ ],+ });+ expect(+ await resolveVercelDeploymentEvent({+ github,+ owner: 'facebook',+ repo: 'astryx',+ deployment,+ status,+ }),+ ).toEqual({prNumber: 123, headSha: SHA, origin: ORIGIN});+ expect(github.paginate).toHaveBeenCalledWith(github.rest.pulls.list, {+ owner: 'facebook',+ repo: 'astryx',+ state: 'open',+ per_page: 100,+ });+ }+ });++ it('ignores unrelated deployments and refuses ambiguous or stale PR associations', async () => {+ const deployment = {+ id: 7,+ sha: SHA,+ environment: 'Preview',+ creator: {login: 'vercel[bot]'},+ };+ const status = {state: 'success', environment_url: ORIGIN};+ for (const invalid of [+ {deployment: {...deployment, environment: 'Production'}, status},+ {deployment, status: {...status, state: 'pending'}},+ {deployment: {...deployment, creator: {login: 'other'}}, status},+ ]) {+ const github = fixture();+ expect(+ await resolveVercelDeploymentEvent({+ github,+ owner: 'facebook',+ repo: 'astryx',+ ...invalid,+ }),+ ).toBeNull();+ expect(github.paginate).not.toHaveBeenCalled();+ }+ const candidate = {+ number: 123,+ state: 'open',+ draft: false,+ head: {sha: SHA},+ base: {repo: {full_name: 'facebook/astryx'}},+ };+ for (const candidates of [+ [{...candidate, draft: true}],+ [{...candidate, head: {sha: OLD_SHA}}],+ [candidate, {...candidate, number: 124}],+ ]) {+ const github = fixture({candidates});+ expect(+ await resolveVercelDeploymentEvent({+ github,+ owner: 'facebook',+ repo: 'astryx',+ deployment,+ status,+ }),+ ).toBeNull();+ }+ });+});diff --git a/.github/scripts/visual-gate/workflow-concurrency.test.mjs b/.github/scripts/visual-gate/workflow-concurrency.test.mjsindex 68a40f3c09..a6cf936b4f 100644--- a/.github/scripts/visual-gate/workflow-concurrency.test.mjs+++ b/.github/scripts/visual-gate/workflow-concurrency.test.mjs@@ -1,23 +1,26 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+import {execFileSync} from 'node:child_process';import fs from 'node:fs';+import os from 'node:os';import path from 'node:path';import {fileURLToPath} from 'node:url';import {describe, expect, it} from 'vitest';+import yaml from 'yaml';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),'../../..',);-const WORKFLOWS = path.join(ROOT, '.github', 'workflows');+const WORKFLOWS = path.join(ROOT, '.github/workflows');function workflow(name) {return fs.readFileSync(path.join(WORKFLOWS, name), 'utf8');}describe('PR report and deployment workflow contracts', () => {- it('publishes canonical CI artifacts without another capture, comparison, or status owner', () => {+ it('publishes canonical CI visual artifacts without taking over capture, comparison, or status', () => {const value = workflow('pr-comment.yml');expect(value).toContain('name: visual-pr-report');expect(value).toContain('run-id: ${{ steps.identity.outputs.run_id }}');@@ -29,184 +32,193 @@ describe('PR report and deployment workflow contracts', () => {expect(value).not.toMatch(/gate\.mjs (?:check|capture|release)/);expect(value).not.toContain('playwright');expect(value).not.toContain('createCommitStatus');- expect(value).not.toContain('visual-approved');- const publisher = fs.readFileSync(- path.join(ROOT, '.github/scripts/visual-gate/publish-pr-report.mjs'),- 'utf8',- );- expect(publisher).not.toMatch(/from ['"].*(?:capture|compare)\.mjs['"]/);});- it('locks PR report resolution before any mutation', () => {- const value = workflow('pr-comment.yml');- const [header, jobs] = value.split('\njobs:\n');-- expect(header).toContain(- 'group: pr-report-head-${{ github.event.workflow_run.head_repository.id }}-${{ github.event.workflow_run.head_branch }}',+ it('serializes early preview and later CI enrichment per PR, not across PRs', () => {+ const value = yaml.parse(workflow('pr-comment.yml'));+ expect(value.on.deployment_status).toBeDefined();+ expect(value.on.workflow_run.types).toEqual(['completed']);+ expect(value.concurrency).toBeUndefined();+ expect(value.jobs['preview-comment'].concurrency.group).toBe(+ 'pr-report-${{ needs.resolve-preview.outputs.pr_number }}',+ );+ for (const job of ['comment', 'spec-only-reconcile']) {+ expect(value.jobs[job].concurrency.group).toBe(+ 'pr-report-${{ needs.resolve.outputs.pr_number }}',+ );+ expect(value.jobs[job].concurrency['cancel-in-progress']).toBe(false);+ }+ expect(workflow('pr-comment.yml')).toContain(+ 'validateAnalysisMetadata(metadata, {',);- expect(header).toContain('cancel-in-progress: false');- expect(jobs).not.toContain('visual-acceptance-pr-');- expect(jobs).not.toContain(' concurrency:');});- it('uses the shared metadata validator for exact and legacy PR artifacts', () => {+ it('routes Vercel success directly to a trusted early comment and CI completion to enrichment', () => {const value = workflow('pr-comment.yml');- const crossCheck = value.slice(- value.indexOf(' - name: Cross-check artifact identity'),- value.indexOf(' - name: Prepare canonical visual report'),+ const jobs = yaml.parse(value).jobs;+ expect(jobs['resolve-preview'].if).toContain(+ "github.event_name == 'deployment_status'",);-- expect(crossCheck).toContain('import {validateAnalysisMetadata}');- expect(crossCheck).toContain('validateAnalysisMetadata(metadata, {');- expect(crossCheck).not.toContain('meta.headSha !==');+ expect(jobs['resolve-preview'].if).toContain(+ "github.event.deployment.environment == 'Preview'",+ );+ expect(jobs['resolve-preview'].if).toContain(+ "github.event.deployment.creator.login == 'vercel[bot]'",+ );+ expect(jobs['resolve-preview'].steps[0].with.ref).toBe('main');+ const guard = jobs['resolve-preview'].steps[1];+ expect(guard.run).toContain('available=false');+ expect(guard.run).toContain('Preview resolver is not on trusted main yet');+ expect(jobs['resolve-preview'].steps[2].if).toBe(+ "steps.trusted.outputs.available == 'true'",+ );+ expect(jobs['resolve-preview'].steps[2].with.script).toContain(+ 'resolveVercelDeploymentEvent',+ );+ expect(jobs['preview-comment'].needs).toBe('resolve-preview');+ expect(jobs['preview-comment'].steps[1].with.script).toContain(+ 'reconcileEarlyPreviewComment',+ );+ expect(jobs.resolve.if).toContain("github.event_name == 'workflow_run'");+ expect(jobs.comment.needs).toEqual(['resolve', 'deploy-preview']);+ expect(jobs.comment.permissions.deployments).toBe('read');});- it('orders trusted preview publication before comment reconciliation', () => {- const publisher = workflow('deploy-preview.yml');- const comment = workflow('pr-comment.yml');-- expect(publisher).toContain('workflow_call:');- expect(publisher).toContain('source_run_attempt:');- expect(publisher).toContain('--result preview-deployment.json');- expect(comment).toContain('uses: ./.github/workflows/deploy-preview.yml');- expect(comment).toContain('needs: [resolve, deploy-preview]');- expect(comment).toContain(- "if: always() && steps.identity.outputs.valid == 'true'",- );- expect(comment).toContain('reconcilePrComment');- expect(comment).not.toContain('const previewAvailable');+ it('skips pre-merge deployment events when the resolver is absent from trusted main', () => {+ const guard = yaml.parse(workflow('pr-comment.yml')).jobs['resolve-preview']+ .steps[1];+ const root = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-preview-bootstrap-'),+ );+ const output = path.join(root, 'outputs');+ try {+ const run = () =>+ execFileSync('bash', ['-e', '-c', guard.run], {+ cwd: root,+ env: {...process.env, GITHUB_OUTPUT: output},+ encoding: 'utf8',+ });+ expect(run()).toContain('Preview resolver is not on trusted main yet');+ expect(fs.readFileSync(output, 'utf8')).toContain('available=false');+ fs.mkdirSync(path.join(root, '.github/scripts/lib'), {recursive: true});+ fs.writeFileSync(+ path.join(root, '.github/scripts/lib/vercel-preview.mjs'),+ 'trusted main',+ );+ fs.writeFileSync(output, '');+ expect(run()).toBe('');+ expect(fs.readFileSync(output, 'utf8')).toContain('available=true');+ } finally {+ fs.rmSync(root, {recursive: true, force: true});+ }});- it('keeps spec-only checks lightweight while removing stale links', () => {+ it('reconciles spec-only comments without creating a preview or extra build', () => {const value = workflow('pr-comment.yml');const reconcile = value.slice(value.indexOf(' spec-only-reconcile:'),- value.indexOf(' deploy-preview:'),- );- const deploy = value.slice(- value.indexOf(' deploy-preview:'),value.indexOf(' comment:'),);-- expect(value).toContain("needs.resolve.outputs.spec_only == 'true'");expect(reconcile).toContain('reconcilePrComment');expect(reconcile).toContain('createIfMissing: false');expect(reconcile).not.toContain('Setup Node and pnpm');- expect(deploy).toContain("needs.resolve.outputs.spec_only != 'true'");+ expect(value).toContain("needs.resolve.outputs.spec_only != 'true'");});- it('enforces the main-push stable-site chain through the Actions Pages deployer', () => {- const stableSite = workflow('deploy.yml');- const pages = workflow('pages-deploy.yml');- const stableSiteHeader = stableSite.slice(- 0,- stableSite.indexOf('\npermissions:'),+ it('keeps visual checks on their canonical CI Storybook artifact', () => {+ const value = workflow('ci.yml');+ const visual = value.slice(+ value.indexOf(' pr-visual:'),+ value.indexOf(' pr-rtl-shard:'),);-- expect(stableSiteHeader).toContain('name: Deploy');- expect(stableSiteHeader).toContain("branches: ['main']");- expect(stableSite).toContain(- 'node .github/scripts/gh-pages-publisher.mjs stable-site --source staged',+ expect(visual).toContain(+ 'needs: [build-storybook, check-components, maintenance-request]',+ );+ expect(visual).toContain(+ 'name: storybook-${{ needs.build-storybook.outputs.short_hash }}',+ );+ expect(visual).toContain('name: visual-pr-report');+ expect(value).toContain('name: pr-analysis');+ expect(value).not.toContain(+ 'storybook_url=https://${REPO_OWNER}.github.io',+ );+ expect(value).toContain(+ 'name: sandbox-${{ steps.urls.outputs.short_hash }}',);- expect(pages).toContain("- 'Deploy'");- expect(pages).toContain('ref: gh-pages');- expect(pages).toContain('actions/upload-pages-artifact@v5');- expect(pages).toContain('actions/deploy-pages@v5');- });-- it('deploys the latest gh-pages snapshot without cancelling an active deployment', () => {- const pages = workflow('pages-deploy.yml');- const reusablePreview = workflow('deploy-preview.yml');- const prComment = workflow('pr-comment.yml');- const directPublisherNames = fs- .readdirSync(WORKFLOWS)- .filter(file => file.endsWith('.yml'))- .filter(file => file !== 'deploy-preview.yml')- .map(file => workflow(file))- .filter(value => value.includes('gh-pages-publisher.mjs'))- .map(value => value.match(/^name: (.+)$/m)?.[1])- .filter(Boolean);-- for (const source of directPublisherNames) {- expect(pages).toContain(`- '${source}'`);- }- expect(reusablePreview).toContain('workflow_call:');- expect(prComment).toContain('uses: ./.github/workflows/deploy-preview.yml');- expect(pages).toContain("- 'PR Comment'");- expect(pages).toContain('workflow_dispatch:');- const deployJob = pages.slice(pages.indexOf(' deploy:'));- expect(deployJob).toContain('runs-on: ubuntu-latest');- expect(deployJob).toContain('timeout-minutes: 60');- expect(deployJob).not.toContain('runs-on: ubuntu-slim');- expect(pages).toContain('group: github-pages-deployment');- expect(pages).toContain('cancel-in-progress: false');- expect(pages).toContain('pages: write');- expect(pages).toContain('id-token: write');- expect(pages).toContain('actions/configure-pages@v6');});- it('queues an Actions deployment after the supported manual report publisher', () => {- const report = fs.readFileSync(- path.join(ROOT, 'internal/vibe-tests/src/deploy-report.ts'),+ it('hosts only Storybook on Vercel and preserves Sandbox Pages publication', () => {+ const config = JSON.parse(+ fs.readFileSync(path.join(ROOT, 'apps/docsite/vercel.json'), 'utf8'),+ );+ expect(config.buildCommand).toContain(+ 'node apps/docsite/scripts/build-previews.mjs',+ );+ expect(config.buildCommand).toContain(+ 'pnpm -F @astryxdesign/docsite build',+ );+ const builder = fs.readFileSync(+ path.join(ROOT, 'apps/docsite/scripts/build-previews.mjs'),'utf8',);- const publish = report.indexOf('gh-pages-publisher.mjs vibe-report');- const deploy = report.indexOf(- 'gh workflow run pages-deploy.yml --repo ${shellQuote(repository)} --ref main',+ expect(builder).toContain("deploymentEnv !== 'preview'");+ expect(builder).toContain('buildStorybookPreview(deploymentEnv, root');+ expect(builder).not.toContain("'@astryxdesign/sandbox'");+ const comment = workflow('pr-comment.yml');+ expect(comment).toContain('uses: ./.github/workflows/deploy-preview.yml');+ expect(comment).toContain('preview-deployment-');+ expect(comment).toContain('deployments: read');+ expect(workflow('deploy-preview.yml')).not.toContain(+ '--storybook storybook-dist',);-- expect(publish).toBeGreaterThan(-1);- expect(deploy).toBeGreaterThan(publish);- });-- it('verifies exact source identity before checking preview artifacts', () => {- const value = workflow('deploy-preview.yml');- const resolve = value.indexOf(- 'Confirm trusted source and preview identity',+ expect(workflow('redeploy-preview.yml')).not.toContain(+ '--storybook storybook-dist',);- const metadata = value.indexOf(- 'Download PR metadata from the exact CI run',+ expect(workflow('deploy-preview.yml')).toContain('--sandbox sandbox-dist');+ expect(workflow('redeploy-preview.yml')).toContain(+ '--sandbox sandbox-dist',);- const crossCheck = value.indexOf('Cross-check artifact identity');-- expect(value).toContain('workflow_call:');- expect(value).toContain('confirmSourceRunIdentity');- expect(value).toContain('head_repository_id:');- expect(value).toContain('base_repository:');- expect(value).toContain('source_run_attempt:');- expect(value).not.toContain('listPullRequestsAssociatedWithCommit');- expect(resolve).toBeGreaterThan(-1);- expect(resolve).toBeLessThan(metadata);- expect(metadata).toBeLessThan(crossCheck);- expect(value).toContain('validateAnalysisMetadata');- expect(value).toContain('steps.artifact.outputs.ready');+ const publisher = fs.readFileSync(+ path.join(ROOT, '.github/scripts/lib/gh-pages-publisher.mjs'),+ 'utf8',+ );+ expect(publisher).toContain("command === 'pr-preview'");+ expect(publisher).toContain('Storybook previews are hosted on Vercel');+ const reconciler = fs.readFileSync(+ path.join(ROOT, '.github/scripts/lib/pr-preview.mjs'),+ 'utf8',+ );+ expect(reconciler).toContain('resolveVercelPreview');+ expect(reconciler).toContain('`${previewOrigin}/storybook/`');+ expect(reconciler).toContain('pagesURL(identity, sandboxPath)');});- it('rechecks independent target readiness immediately before publishing', () => {- const value = workflow('deploy-preview.yml');- const detect = value.indexOf(- 'Detect independently available preview targets',+ it('defers full-tree cleanup and retains required visual evidence and stable-site writers', () => {+ const cleanup = yaml.parse(workflow('cleanup-previews.yml'));+ expect(cleanup.on.schedule).toEqual([{cron: '0 6 * * *'}]);+ expect(cleanup.on.workflow_dispatch).toBeDefined();+ expect(cleanup.on.workflow_run).toBeUndefined();+ const stable = workflow('deploy.yml');+ const pages = workflow('pages-deploy.yml');+ expect(stable).toContain(+ 'gh-pages-publisher.mjs stable-site --source staged',);- const final = value.indexOf(- 'Confirm preview target immediately before publication',+ expect(pages).toContain("- 'Deploy'");+ expect(pages).toContain("- 'PR Comment'");+ expect(pages).toContain("- 'Re-deploy Preview'");+ expect(pages).toContain(+ "github.event.workflow_run.event == 'workflow_dispatch'",);- const publish = value.indexOf('Publish trusted preview result');- const finalBlock = value.slice(final, publish);- const publishBlock = value.slice(publish);-- expect(final).toBeGreaterThan(detect);- expect(final).toBeLessThan(publish);- expect(finalBlock).toContain('confirmSourceRunIdentity');- expect(finalBlock).toContain('identity.draft');- expect(finalBlock).toContain("'storybook',");- expect(finalBlock).toContain("'sandbox',");- expect(publishBlock).toContain(- "if: always() && steps.final.outputs.ready == 'true'",+ expect(pages).toContain('actions/deploy-pages@v5');+ expect(workflow('pr-comment.yml')).toContain(+ 'gh-pages-publisher.mjs immutable-path',+ );+ expect(workflow('ci.yml')).toContain(+ 'gh-pages-publisher.mjs visual-baseline-manual',);- expect(publishBlock).toContain('--result preview-deployment.json');});- it('keeps every remaining gh-pages writer behind the shared publisher', () => {+ it('retains the remaining Pages publishers behind the shared publisher', () => {const files = ['.github/workflows/deploy-preview.yml','.github/workflows/redeploy-preview.yml',@@ -221,57 +233,13 @@ describe('PR report and deployment workflow contracts', () => {expect(combined).toContain('gh-pages-publisher.mjs');expect(combined).not.toContain('git push origin gh-pages');expect(combined).not.toContain('ref: gh-pages');- expect(combined).not.toContain('git clone --depth 1 --branch gh-pages');- });-- it('grants remaining publisher jobs read access to overlapping workflow runs', () => {- const jobs = [- [workflow('cleanup-previews.yml'), ' cleanup:'],- [workflow('compact-gh-pages.yml'), ' compact:'],- [workflow('vibe-screenshots.yml'), ' deploy-screenshots:'],- ];- for (const [value, jobName] of jobs) {- const job = value.slice(- value.indexOf(jobName),- value.indexOf(' steps:', value.indexOf(jobName)),- );- expect(job).toContain('actions: read');- expect(job).toContain('contents: write');- }- });-- it('routes previews, cleanup, compaction, and vibe screenshots through the shared publisher', () => {- const deployPreview = workflow('deploy-preview.yml');- const redeployPreview = workflow('redeploy-preview.yml');- const cleanup = workflow('cleanup-previews.yml');- const compact = workflow('compact-gh-pages.yml');- const vibe = workflow('vibe-screenshots.yml');-- expect(deployPreview).toContain(- 'node .github/scripts/gh-pages-publisher.mjs "${args[@]}"',- );- expect(deployPreview).toContain('--result preview-deployment.json');- expect(redeployPreview).toContain(- 'node .github/scripts/gh-pages-publisher.mjs "${args[@]}"',- );- expect(redeployPreview).toContain('--result preview-deployment.json');- expect(redeployPreview).toContain('Checkout trusted publisher');- expect(redeployPreview).toContain('ref: main');- expect(redeployPreview.indexOf('Checkout trusted publisher')).toBeLessThan(- redeployPreview.indexOf('--result preview-deployment.json'),- );- expect(cleanup).toContain('gh-pages-publisher.mjs cleanup-previews');- expect(compact).toContain('gh-pages-publisher.mjs compact');- expect(vibe).toContain('gh-pages-publisher.mjs vibe-screenshots');- for (const value of [- deployPreview,- redeployPreview,- cleanup,- compact,- vibe,+ for (const [file, job] of [+ ['cleanup-previews.yml', 'cleanup'],+ ['compact-gh-pages.yml', 'compact'],+ ['vibe-screenshots.yml', 'deploy-screenshots'],]) {- expect(value).not.toContain('git push origin gh-pages');- expect(value).not.toContain('ref: gh-pages');+ const permissions = yaml.parse(workflow(file)).jobs[job].permissions;+ expect(permissions).toMatchObject({actions: 'read', contents: 'write'});}});});diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 129fef6e05..0bf1f40af7 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -562,7 +562,6 @@ jobs:permissions:contents: readoutputs:- storybook_url: ${{ steps.urls.outputs.storybook_url }}short_hash: ${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}sandbox_url: ${{ steps.urls.outputs.sandbox_url }}pr_number: ${{ steps.urls.outputs.pr_number }}@@ -664,7 +663,6 @@ jobs:echo "short_hash=${SHORT_HASH}" >> $GITHUB_OUTPUTecho "pr_number=${PR_NUMBER}" >> $GITHUB_OUTPUT- echo "storybook_url=https://${REPO_OWNER}.github.io/${REPO_NAME}/pr/${PR_NUMBER}/" >> $GITHUB_OUTPUTecho "sandbox_url=https://${REPO_OWNER}.github.io/${REPO_NAME}/pr/${PR_NUMBER}/sandbox/" >> $GITHUB_OUTPUT- name: Identify full release audit scope@@ -715,14 +713,9 @@ jobs:- name: Write PR comment metadataif: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'run: |- # The pr-comment and deploy-preview workflows run on workflow_run- # (privileged token), so they can comment on and deploy previews for- # fork PRs too. Neither context knows the PR number, preview URLs, or- # the artifact hash, so persist them here for the trusted jobs to read.- #- # Preview URLs are now populated for ALL PRs (fork and same-repo alike)- # because deploy-preview.yml deploys every PR's preview from the trusted- # context — the old fork/same-repo split (empty URLs on forks) is gone.+ # PR Comment reads this exact-run analysis. Storybook preview links+ # come from the exact-head Vercel deployment; the Sandbox artifact+ # remains on Pages until its separate migration.cat > pr-meta.json <<EOF{"prNumber": "${{ steps.urls.outputs.pr_number }}",@@ -846,13 +839,10 @@ jobs:*) exit 1 ;;esac- # NOTE: PR preview deploy has moved to deploy-preview.yml (workflow_run).- # It used to live here as a `deploy-preview` job, but a pull_request job on a- # fork gets a read-only GITHUB_TOKEN and can't push to gh-pages — so previews- # only ever appeared on same-repo PRs. The trusted workflow_run companion runs- # in the base-repo context with a write token, downloads the static artifacts- # this workflow already uploads (storybook-<hash>, sandbox-<hash>), and deploys- # for EVERY PR (fork and same-repo alike) without executing any PR code.+ # CI keeps Storybook's static artifact for visual, accessibility, and RTL+ # checks. The Vercel Preview deployment independently hosts human Storybook;+ # the trusted deploy-preview.yml workflow still publishes only Sandbox to Pages+ # after CI for fork and same-repository PRs without running PR code.# Accessibility audit# Skipped when no components changed. Depends only on build-storybook, so itdiff --git a/.github/workflows/cleanup-previews.yml b/.github/workflows/cleanup-previews.ymlindex 8d5df9fa51..a9f1683225 100644--- a/.github/workflows/cleanup-previews.yml+++ b/.github/workflows/cleanup-previews.yml@@ -3,17 +3,10 @@# Cleanup Preview Deployments — removes stale /pr/<number>/ previews and other# leftovers from gh-pages.#-# Runs on workflow_run after CI completes, NOT on pull_request. That matters:-# a pull_request workflow triggered by a fork gets a READ-ONLY token and can't-# push to gh-pages, so the cleanup push failed with a 403 for EVERY fork PR-# (see #4672). workflow_run runs from the base repo with the repo's own write-# token, so cleanup works for fork PRs too — one code path for every PR, no-# drift between a fork path and a same-repo path (mirrors deploy-preview.yml).-#-# The cleanup does not actually need the "closed" event: it reconciles the-# on-disk pr/ dirs against the live open-PR list (`gh pr list`) every run, so-# firing on any PR's CI completion (plus the daily cron) is sufficient to-# garbage-collect closed/merged previews.+# Runs daily (and on manual dispatch), reconciling pr/ against the current+# open-PR list. Preview writes do not wait for this deferred garbage collection.+# Fork PRs require a trusted base-repository token to mutate gh-pages; this+# workflow never executes PR code.## Safety: this NEVER checks out or runs PR-controlled code. It only checks out# gh-pages and deletes stale paths. Do not add checkout of the PR head or@@ -24,9 +17,6 @@ name: Cleanup Preview Deploymentson:schedule:- cron: '0 6 * * *' # Daily 6am UTC- workflow_run:- workflows: ['CI']- types: [completed]workflow_dispatch:inputs:dry_run:@@ -48,12 +38,6 @@ concurrency:jobs:cleanup:- # Only react to CI runs triggered by a pull request (matches- # deploy-preview.yml); scheduled and manual runs have no workflow_run- # payload and always proceed.- if: >-- github.event_name != 'workflow_run' ||- github.event.workflow_run.event == 'pull_request'runs-on: ubuntu-slimpermissions:actions: readdiff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.ymlindex a5bc5df99b..c006c1d366 100644--- a/.github/workflows/deploy-preview.yml+++ b/.github/workflows/deploy-preview.yml@@ -1,9 +1,9 @@# Copyright (c) Meta Platforms, Inc. and affiliates.-# Trusted preview publisher used by pr-comment.yml after an exact pull-request CI-# run completes. The caller resolves the source identity; this workflow verifies-# it again, downloads only that run's static artifacts, and records the published-# targets in a result produced by the shared gh-pages publisher.+# Trusted Sandbox publisher used by pr-comment.yml after an exact PR CI run+# completes. Storybook is hosted by the exact-head Vercel docsite preview.+# The caller resolves the source identity; this workflow checks it again,+# downloads only the matching Sandbox artifact, and records its Pages proof.name: Deploy PR Preview@@ -155,16 +155,6 @@ jobs:core.setOutput('ready', 'false');}- - name: Download Storybook artifact- if: steps.artifact.outputs.ready == 'true'- uses: actions/download-artifact@v8- with:- name: storybook-${{ steps.identity.outputs.short_hash }}- path: storybook-dist- run-id: ${{ inputs.source_run_id }}- github-token: ${{ secrets.GITHUB_TOKEN }}- continue-on-error: true-- name: Download Sandbox artifactif: steps.artifact.outputs.ready == 'true'uses: actions/download-artifact@v8@@ -175,15 +165,10 @@ jobs:github-token: ${{ secrets.GITHUB_TOKEN }}continue-on-error: true- - name: Detect independently available preview targets+ - name: Detect Sandbox readinessid: targetsif: always() && steps.identity.outputs.valid == 'true'run: |- if [ "${{ steps.artifact.outputs.ready }}" = 'true' ] && [ -f storybook-dist/index.html ]; then- echo "storybook=true" >> "$GITHUB_OUTPUT"- else- echo "storybook=false" >> "$GITHUB_OUTPUT"- fiif [ "${{ steps.artifact.outputs.ready }}" = 'true' ] && [ -f sandbox-dist/index.html ]; thenecho "sandbox=true" >> "$GITHUB_OUTPUT"else@@ -204,7 +189,6 @@ jobs:SOURCE_RUN_ID: ${{ inputs.source_run_id }}SOURCE_RUN_ATTEMPT: ${{ inputs.source_run_attempt }}SOURCE_CONCLUSION: ${{ inputs.source_conclusion }}- STORYBOOK_CANDIDATE: ${{ steps.targets.outputs.storybook }}SANDBOX_CANDIDATE: ${{ steps.targets.outputs.sandbox }}with:retries: 3@@ -230,10 +214,6 @@ jobs:});const mayPublish = identity.sourceConclusion === 'success' && !identity.draft;core.setOutput('ready', 'true');- core.setOutput(- 'storybook',- String(mayPublish && process.env.STORYBOOK_CANDIDATE === 'true'),- );core.setOutput('sandbox',String(mayPublish && process.env.SANDBOX_CANDIDATE === 'true'),@@ -252,7 +232,6 @@ jobs:SOURCE_RUN_ID: ${{ inputs.source_run_id }}SOURCE_RUN_ATTEMPT: ${{ inputs.source_run_attempt }}SOURCE_CONCLUSION: ${{ inputs.source_conclusion }}- STORYBOOK_AVAILABLE: ${{ steps.final.outputs.storybook }}SANDBOX_AVAILABLE: ${{ steps.final.outputs.sandbox }}run: |args=(@@ -268,9 +247,6 @@ jobs:--source-conclusion "$SOURCE_CONCLUSION"--result preview-deployment.json)- if [ "$STORYBOOK_AVAILABLE" = 'true' ]; then- args+=(--storybook storybook-dist)- fiif [ "$SANDBOX_AVAILABLE" = 'true' ]; thenargs+=(--sandbox sandbox-dist)fidiff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.ymlindex 78c5f0695c..f635d281b8 100644--- a/.github/workflows/pages-deploy.yml+++ b/.github/workflows/pages-deploy.yml@@ -35,6 +35,17 @@ concurrency:jobs:source:+ # PR CI and early Vercel preview comments do not write Pages bytes. Preserve+ # explicit baseline-maintenance CI dispatches and CI-backed PR Comment runs+ # (which may publish immutable visual evidence).+ if: >-+ github.event_name != 'workflow_run' ||+ (github.event.workflow_run.name == 'CI' &&+ github.event.workflow_run.event == 'workflow_dispatch') ||+ (github.event.workflow_run.name == 'PR Comment' &&+ github.event.workflow_run.event == 'workflow_run') ||+ (github.event.workflow_run.name != 'CI' &&+ github.event.workflow_run.name != 'PR Comment')runs-on: ubuntu-slimpermissions:pages: readdiff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.ymlindex f61534e1d9..81d51780f5 100644--- a/.github/workflows/pr-comment.yml+++ b/.github/workflows/pr-comment.yml@@ -10,9 +10,9 @@# drift between a fork path and a same-repo path.## Safety: resolves scope and PR identity from the GitHub API. Privileged jobs-# check out only trusted default-branch code. PR-built static artifacts are-# published only after exact run/PR/repository checks; report fields remain-# untrusted data and are rendered by default-branch code.+# check out only trusted default-branch code. The Storybook URL is resolved+# from GitHub's exact-head Vercel deployment, while Sandbox Pages proof comes+# from the validated source CI artifact. PR artifacts remain static data.name: PR Comment@@ -20,17 +20,13 @@ on:workflow_run:workflows: ['CI']types: [completed]+ deployment_status:permissions: {}-# Serialize report publication for a head without cancelling a Pages writer.-concurrency:- group: pr-report-head-${{ github.event.workflow_run.head_repository.id }}-${{ github.event.workflow_run.head_branch }}- cancel-in-progress: false-jobs:resolve:- if: github.event.workflow_run.event == 'pull_request'+ if: github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request'runs-on: ubuntu-slimpermissions:contents: read@@ -109,8 +105,110 @@ jobs:core.setOutput('spec_only', String(changeScope.specOnly));core.setOutput('tooling_only', String(changeScope.toolingOnly));+ resolve-preview:+ if: >-+ github.event_name == 'deployment_status' &&+ github.event.deployment_status.state == 'success' &&+ github.event.deployment.environment == 'Preview' &&+ github.event.deployment.creator.login == 'vercel[bot]'+ runs-on: ubuntu-slim+ permissions:+ contents: read+ pull-requests: read+ deployments: read+ outputs:+ valid: ${{ steps.preview.outputs.valid }}+ pr_number: ${{ steps.preview.outputs.pr_number }}+ head_sha: ${{ steps.preview.outputs.head_sha }}+ origin: ${{ steps.preview.outputs.origin }}+ steps:+ - name: Checkout trusted default-branch code+ uses: actions/checkout@v7+ with:+ ref: main++ - name: Check trusted resolver availability+ id: trusted+ run: |+ if [ -f .github/scripts/lib/vercel-preview.mjs ]; then+ echo "available=true" >> "$GITHUB_OUTPUT"+ else+ # A new deployment_status workflow can run before its helper lands+ # on main. Never load the untrusted PR branch as a substitute.+ echo "available=false" >> "$GITHUB_OUTPUT"+ echo "::notice::Preview resolver is not on trusted main yet; skipping this deployment."+ fi++ - name: Resolve current Vercel PR preview+ id: preview+ if: steps.trusted.outputs.available == 'true'+ uses: actions/github-script@v9+ with:+ retries: 3+ script: |+ const {pathToFileURL} = require('node:url');+ const {resolveVercelDeploymentEvent} = await import(+ pathToFileURL(`${process.env.GITHUB_WORKSPACE}/.github/scripts/lib/vercel-preview.mjs`).href+ );+ const preview = await resolveVercelDeploymentEvent({+ github,+ ...context.repo,+ deployment: context.payload.deployment,+ status: context.payload.deployment_status,+ });+ if (!preview) {+ core.notice('No current, non-draft PR matches this exact Vercel Preview deployment.');+ core.setOutput('valid', 'false');+ return;+ }+ core.setOutput('valid', 'true');+ core.setOutput('pr_number', String(preview.prNumber));+ core.setOutput('head_sha', preview.headSha);+ core.setOutput('origin', preview.origin);++ preview-comment:+ needs: resolve-preview+ if: needs.resolve-preview.outputs.valid == 'true'+ concurrency:+ group: pr-report-${{ needs.resolve-preview.outputs.pr_number }}+ cancel-in-progress: false+ runs-on: ubuntu-slim+ permissions:+ contents: read+ pull-requests: write+ deployments: read+ steps:+ - name: Checkout trusted default-branch code+ uses: actions/checkout@v7+ with:+ ref: main++ - name: Post exact-head preview links before CI completes+ uses: actions/github-script@v9+ env:+ PR_NUMBER: ${{ needs.resolve-preview.outputs.pr_number }}+ HEAD_SHA: ${{ needs.resolve-preview.outputs.head_sha }}+ PREVIEW_ORIGIN: ${{ needs.resolve-preview.outputs.origin }}+ with:+ retries: 3+ script: |+ const {pathToFileURL} = require('node:url');+ const {reconcileEarlyPreviewComment} = await import(+ pathToFileURL(`${process.env.GITHUB_WORKSPACE}/.github/scripts/lib/pr-preview.mjs`).href+ );+ await reconcileEarlyPreviewComment({+ github,+ ...context.repo,+ prNumber: Number(process.env.PR_NUMBER),+ headSha: process.env.HEAD_SHA,+ origin: process.env.PREVIEW_ORIGIN,+ });+spec-only-reconcile:needs: resolve+ concurrency:+ group: pr-report-${{ needs.resolve.outputs.pr_number }}+ cancel-in-progress: falseif: >-github.event.action == 'completed' &&needs.resolve.outputs.valid == 'true' &&@@ -197,8 +295,11 @@ jobs:comment:needs: [resolve, deploy-preview]- # Reconcile after the trusted publisher settles. A failed publisher still- # runs this job so stale links are removed rather than retained.+ concurrency:+ group: pr-report-${{ needs.resolve.outputs.pr_number }}+ cancel-in-progress: false+ # Sandbox Pages publication settles before CI evidence reconciliation;+ # Storybook links come from the exact-head Vercel deployment independently.if: >-always() &&github.event.action == 'completed' &&@@ -209,6 +310,7 @@ jobs:permissions:pull-requests: writeactions: read+ deployments: read # resolve the exact-head Vercel Preview deploymentcontents: write # immutable validated visual evidence on gh-pagessteps:- name: Checkout trusted default-branch codediff --git a/.github/workflows/redeploy-preview.yml b/.github/workflows/redeploy-preview.ymlindex 9f46391948..aa4a22772f 100644--- a/.github/workflows/redeploy-preview.yml+++ b/.github/workflows/redeploy-preview.yml@@ -1,7 +1,7 @@# Copyright (c) Meta Platforms, Inc. and affiliates.-# Re-publishes whatever independent preview artifacts remain for a PR's latest-# successful CI run. It never checks out or executes the PR head.+# Re-publishes the Sandbox artifact from the PR's latest successful CI run.+# Storybook lives with the exact-head Vercel docsite preview.name: Re-deploy Preview@@ -146,15 +146,6 @@ jobs:},);- - name: Download Storybook artifact- uses: actions/download-artifact@v8- with:- name: storybook-${{ steps.source.outputs.short_hash }}- path: storybook-dist- run-id: ${{ steps.source.outputs.run_id }}- github-token: ${{ secrets.GITHUB_TOKEN }}- continue-on-error: true-- name: Download Sandbox artifactuses: actions/download-artifact@v8with:@@ -164,17 +155,11 @@ jobs:github-token: ${{ secrets.GITHUB_TOKEN }}continue-on-error: true- - name: Detect independently available preview targets+ - name: Detect available Sandbox artifactid: targetsrun: |- storybook=false- sandbox=false- if [ -f storybook-dist/index.html ]; then storybook=true; fi- if [ -f sandbox-dist/index.html ]; then sandbox=true; fi- echo "storybook=$storybook" >> "$GITHUB_OUTPUT"- echo "sandbox=$sandbox" >> "$GITHUB_OUTPUT"- if [ "$storybook" != 'true' ] && [ "$sandbox" != 'true' ]; then- echo "::error::No preview artifact remains for source run ${{ steps.source.outputs.run_id }}. Re-run CI on the PR."+ if [ ! -f sandbox-dist/index.html ]; then+ echo "::error::No Sandbox artifact remains for source run ${{ steps.source.outputs.run_id }}. Re-run CI on the PR."exit 1fi@@ -213,7 +198,7 @@ jobs:});if (identity.draft) core.setFailed(`PR #${identity.prNumber} is still a draft.`);- - name: Deploy available targets to GitHub Pages+ - name: Deploy Sandbox to GitHub Pagesenv:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}PR_NUMBER: ${{ steps.source.outputs.pr_number }}@@ -224,8 +209,6 @@ jobs:BASE_REPOSITORY: ${{ steps.source.outputs.base_repo }}SOURCE_RUN_ID: ${{ steps.source.outputs.run_id }}SOURCE_RUN_ATTEMPT: ${{ steps.source.outputs.run_attempt }}- STORYBOOK_AVAILABLE: ${{ steps.targets.outputs.storybook }}- SANDBOX_AVAILABLE: ${{ steps.targets.outputs.sandbox }}run: |args=(pr-preview@@ -239,13 +222,8 @@ jobs:--source-run-attempt "$SOURCE_RUN_ATTEMPT"--source-conclusion success--result preview-deployment.json+ --sandbox sandbox-dist)- if [ "$STORYBOOK_AVAILABLE" = 'true' ]; then- args+=(--storybook storybook-dist)- fi- if [ "$SANDBOX_AVAILABLE" = 'true' ]; then- args+=(--sandbox sandbox-dist)- finode .github/scripts/gh-pages-publisher.mjs "${args[@]}"- name: Upload deployment resultdiff --git a/apps/docsite/.gitignore b/apps/docsite/.gitignoreindex eb5066b58f..db289ee722 100644--- a/apps/docsite/.gitignore+++ b/apps/docsite/.gitignore@@ -13,6 +13,9 @@ public/playground-types.jsonpublic/monaco/public/vendor/+# Vercel stages the built Storybook beside preview/canary docs, never in source control.+public/storybook/+# Auto-generated by `astryx theme build` (pnpm build:theme). The theme source# lives at src/themes/astryxTheme.ts; the built JS/CSS/d.ts files are# regenerated locally and in CI before next dev / next build.diff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjsindex 5b32c4f4f2..3b66ee7c5e 100644--- a/apps/docsite/next.config.mjs+++ b/apps/docsite/next.config.mjs@@ -1,5 +1,12 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file Configure the docsite's routes, response headers, and theme resolution.+ * @input Next.js build configuration and staged Storybook static export.+ * @output Docsite routes plus preview-only Storybook HTML at /storybook/.+ * @position Next.js configuration for the existing Vercel docsite deployment.+ */+import {readdirSync} from 'node:fs';import {resolve} from 'node:path';@@ -8,8 +15,13 @@ const nextConfig = {cacheComponents: true,// A dynamic route segment can't carry a static extension, so the public// plaintext URL /blog/<slug>.txt is served by the /blog/txt/[slug] handler.+ // Storybook's exported index.html is a static file, not a Next.js route.+ // Its other files are served directly from public/ before this rewrite.async rewrites() {- return [{source: '/blog/:slug.txt', destination: '/blog/txt/:slug'}];+ return [+ {source: '/blog/:slug.txt', destination: '/blog/txt/:slug'},+ {source: '/storybook', destination: '/storybook/index.html'},+ ];},// The playground preview evaluates user-authored code, so it is the one// route that must never be embeddable by another site and never a loader ofdiff --git a/apps/docsite/scripts/build-previews.mjs b/apps/docsite/scripts/build-previews.mjsnew file mode 100644index 0000000000..02b44acb96--- /dev/null+++ b/apps/docsite/scripts/build-previews.mjs@@ -0,0 +1,79 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Build and stage Storybook in the existing Vercel docsite preview.+ * @input VERCEL_ENV and the Storybook static build.+ * @output apps/docsite/public/storybook only in preview/canary deployments.+ * @position Build-time staging before the docsite Next.js build; CI retains its own visual artifact.+ */++import {execFileSync} from 'node:child_process';+import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';++export function stageStorybook(source, destination) {+ const index = path.join(source, 'index.html');+ if (!fs.existsSync(index) || !fs.statSync(index).isFile()) {+ throw new Error(`Storybook build has no index.html: ${index}`);+ }+ const html = fs.readFileSync(index, 'utf8');+ const head = html.match(/<head(?:\s[^>]*)?>/i)?.[0];+ if (!head || /<base\b/i.test(html)) {+ throw new Error(+ 'Storybook index.html must have a head without a base element',+ );+ }++ // Next.js redirects /storybook/ to /storybook. Fix the base for relative+ // manager, iframe, and asset URLs without changing Storybook's CI build.+ fs.rmSync(destination, {recursive: true, force: true});+ fs.cpSync(source, destination, {recursive: true});+ fs.writeFileSync(+ indexPath(destination),+ html.replace(head, `${head}\n <base href="/storybook/" />`),+ );+}++function indexPath(directory) {+ return path.join(directory, 'index.html');+}++export function buildStorybookPreview(deploymentEnv, root, run = execFileSync) {+ const destination = path.join(root, 'apps/docsite/public/storybook');+ if (deploymentEnv !== 'preview') {+ // Release docs must never package an earlier cached preview.+ fs.rmSync(destination, {recursive: true, force: true});+ return;+ }++ try {+ const output = run('pnpm', ['-F', '@astryxdesign/storybook', 'build'], {+ cwd: root,+ encoding: 'utf8',+ maxBuffer: 64 * 1024 * 1024,+ });+ if (output) process.stdout.write(output);+ } catch (error) {+ const detail = [error.stdout, error.stderr]+ .filter(Boolean)+ .join('\n')+ .slice(-12000);+ throw new Error(+ `Storybook preview build failed:\n${detail || error.message}`,+ {cause: error},+ );+ }+ stageStorybook(path.join(root, 'apps/storybook/dist'), destination);+}++if (+ process.argv[1] &&+ path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)+) {+ const root = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../..',+ );+ buildStorybookPreview(process.env.VERCEL_ENV, root);+}diff --git a/apps/docsite/scripts/build-previews.test.mjs b/apps/docsite/scripts/build-previews.test.mjsnew file mode 100644index 0000000000..5acb9c0c7f--- /dev/null+++ b/apps/docsite/scripts/build-previews.test.mjs@@ -0,0 +1,97 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {afterEach, test} from 'node:test';++import {buildStorybookPreview, stageStorybook} from './build-previews.mjs';++const roots = [];+function fixture() {+ const root = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-storybook-preview-'),+ );+ roots.push(root);+ const source = path.join(root, 'apps/storybook/dist');+ const destination = path.join(root, 'apps/docsite/public/storybook');+ fs.mkdirSync(path.join(source, 'assets'), {recursive: true});+ fs.writeFileSync(+ path.join(source, 'index.html'),+ '<html><head></head><body>Storybook</body></html>',+ );+ fs.writeFileSync(path.join(source, 'assets/manager.js'), 'manager bytes');+ return {root, source, destination};+}+afterEach(() => {+ for (const root of roots.splice(0))+ fs.rmSync(root, {recursive: true, force: true});+});++test('stages a complete Storybook under a stable /storybook/ asset base', () => {+ const {source, destination} = fixture();+ fs.mkdirSync(destination, {recursive: true});+ fs.writeFileSync(path.join(destination, 'stale.js'), 'old');+ stageStorybook(source, destination);+ assert.match(+ fs.readFileSync(path.join(destination, 'index.html'), 'utf8'),+ /<base href="\/storybook\/" \/>/,+ );+ assert.equal(+ fs.readFileSync(path.join(destination, 'assets/manager.js'), 'utf8'),+ 'manager bytes',+ );+ assert.equal(fs.existsSync(path.join(destination, 'stale.js')), false);+});++test('rejects an incomplete or incompatible export before touching staged bytes', () => {+ const {source, destination} = fixture();+ fs.mkdirSync(destination, {recursive: true});+ fs.writeFileSync(path.join(destination, 'index.html'), 'old');+ for (const html of [null, 'not HTML', '<head><base href="/other/"></head>']) {+ if (html === null) fs.rmSync(path.join(source, 'index.html'));+ else fs.writeFileSync(path.join(source, 'index.html'), html);+ assert.throws(+ () => stageStorybook(source, destination),+ /Storybook (?:build has no index.html|index.html must have a head)/,+ );+ assert.equal(+ fs.readFileSync(path.join(destination, 'index.html'), 'utf8'),+ 'old',+ );+ }+});++test('only preview/canary Vercel builds create the Storybook route', () => {+ const {root, destination} = fixture();+ const calls = [];+ buildStorybookPreview('preview', root, (command, args, options) => {+ calls.push({command, args, options});+ });+ assert.deepEqual(+ calls.map(({command, args}) => [command, args]),+ [['pnpm', ['-F', '@astryxdesign/storybook', 'build']]],+ );+ assert.equal(fs.existsSync(path.join(destination, 'index.html')), true);+ for (const env of ['production', 'development', undefined]) {+ buildStorybookPreview(env, root, () => {+ throw new Error('should not run');+ });+ assert.equal(fs.existsSync(destination), false);+ }+});++test('reports captured build output on a failed Storybook build', () => {+ const {root} = fixture();+ assert.throws(+ () =>+ buildStorybookPreview('preview', root, () => {+ throw Object.assign(new Error('command failed'), {+ stdout: 'building',+ stderr: 'failed to compile',+ });+ }),+ /Storybook preview build failed:\nbuilding\nfailed to compile/,+ );+});diff --git a/apps/docsite/vercel.json b/apps/docsite/vercel.jsonindex da6722248a..5479bf5783 100644--- a/apps/docsite/vercel.json+++ b/apps/docsite/vercel.json@@ -1,4 +1,4 @@{"installCommand": "cd ../.. && node scripts/clean-workspace-node-modules.mjs && pnpm install --force --frozen-lockfile",- "buildCommand": "cd ../.. && pnpm build && pnpm -F @astryxdesign/docsite build"+ "buildCommand": "cd ../.. && pnpm build && node apps/docsite/scripts/build-previews.mjs && pnpm -F @astryxdesign/docsite build"}