Skip to content

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.js
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.yml
index 129fef6e05..0bf1f40af7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -562,7 +562,6 @@ jobs:
permissions:
contents: read
outputs:
- 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_OUTPUT
echo "pr_number=${PR_NUMBER}" >> $GITHUB_OUTPUT
- echo "storybook_url=https://${REPO_OWNER}.github.io/${REPO_NAME}/pr/${PR_NUMBER}/" >> $GITHUB_OUTPUT
echo "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 metadata
if: 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 it
diff --git a/.github/workflows/cleanup-previews.yml b/.github/workflows/cleanup-previews.yml
index 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 Deployments
on:
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-slim
permissions:
actions: read
diff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.yml
index 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 artifact
if: 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 readiness
id: targets
if: 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"
- fi
if [ "${{ steps.artifact.outputs.ready }}" = 'true' ] && [ -f sandbox-dist/index.html ]; then
echo "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)
- fi
if [ "$SANDBOX_AVAILABLE" = 'true' ]; then
args+=(--sandbox sandbox-dist)
fi
diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml
index 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-slim
permissions:
pages: read
diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml
index 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-slim
permissions:
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: false
if: >-
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: write
actions: read
+ deployments: read # resolve the exact-head Vercel Preview deployment
contents: write # immutable validated visual evidence on gh-pages
steps:
- name: Checkout trusted default-branch code
diff --git a/.github/workflows/redeploy-preview.yml b/.github/workflows/redeploy-preview.yml
index 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 artifact
uses: actions/download-artifact@v8
with:
@@ -164,17 +155,11 @@ jobs:
github-token: ${{ secrets.GITHUB_TOKEN }}
continue-on-error: true
- - name: Detect independently available preview targets
+ - name: Detect available Sandbox artifact
id: targets
run: |
- 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 1
fi
@@ -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 Pages
env:
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)
- fi
node .github/scripts/gh-pages-publisher.mjs "${args[@]}"
- name: Upload deployment result
diff --git a/apps/docsite/.gitignore b/apps/docsite/.gitignore
index eb5066b58f..db289ee722 100644
--- a/apps/docsite/.gitignore
+++ b/apps/docsite/.gitignore
@@ -13,6 +13,9 @@ public/playground-types.json
public/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.mjs
index 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 of
diff --git a/apps/docsite/scripts/build-previews.mjs b/apps/docsite/scripts/build-previews.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.json
index 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"
}