Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): gate full ShadCN installability in CI (#6231)

Joey695aeec46b61
diff --git a/.changeset/shadcn-registry-ci.md b/.changeset/shadcn-registry-ci.md
new file mode 100644
index 0000000000..e02a9807f5
--- /dev/null
+++ b/.changeset/shadcn-registry-ci.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Make generated ShadCN compositions match the exact bytes written by the stock client, include package peer dependencies, and require full-catalog install/build coverage in CI.
+
+@josephfarina
diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjs
index ad88d6c342..9b2b4ffe57 100644
--- a/.github/scripts/ci-tooling-routing.test.mjs
+++ b/.github/scripts/ci-tooling-routing.test.mjs
@@ -123,11 +123,16 @@ describe('Node-tooling CI routing', () => {
});
it('preserves the historical joins and fails them on owned-lane failure', () => {
- expect(ci.jobs.test.needs).toEqual(['test-ui', 'test-node']);
+ expect(ci.jobs.test.needs).toEqual([
+ 'test-ui',
+ 'test-node',
+ 'registry-contract',
+ ]);
expect(ci.jobs.build.needs).toEqual(['build-storybook', 'build-sandbox']);
- const testJoin = step(ci.jobs.test, 'Assert both test lanes succeeded').run;
+ const testJoin = step(ci.jobs.test, 'Assert every test gate succeeded').run;
expect(testJoin).toContain('needs.test-node.result');
expect(testJoin).toContain('needs.test-ui.result');
+ expect(testJoin).toContain('needs.registry-contract.result');
const buildJoin = step(
ci.jobs.build,
'Assert parallel builds succeeded',
diff --git a/.github/scripts/shadcn-registry-ci.test.mjs b/.github/scripts/shadcn-registry-ci.test.mjs
new file mode 100644
index 0000000000..1864f6ef79
--- /dev/null
+++ b/.github/scripts/shadcn-registry-ci.test.mjs
@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file shadcn-registry-ci.test.mjs
+ * @description Pins the required full-catalog ShadCN compatibility gate.
+ * @input The PR CI workflow, docsite manifest, and catalog verifier source.
+ * @output Mutation-sensitive assertions for generation, release gating, stock
+ * client installation, compilation, and the historical required join.
+ * @position Workflow contract for spec:AST-026/DEC-7.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {describe, expect, it} from 'vitest';
+import yaml from 'yaml';
+
+const root = path.resolve(import.meta.dirname, '../..');
+const read = relative => fs.readFileSync(path.join(root, relative), 'utf8');
+const ci = yaml.parse(read('.github/workflows/ci.yml'));
+const job = ci.jobs['registry-contract'];
+const SPEC_FALSE = "needs.check-scope.outputs.spec_only != 'true'";
+
+function step(name) {
+ return job.steps.find(candidate => candidate.name === name);
+}
+
+function runLines() {
+ return job.steps
+ .map(candidate => candidate.run)
+ .filter(Boolean)
+ .join('\n');
+}
+
+describe('ShadCN registry CI contract', () => {
+ it('runs as a bounded fail-closed gate and feeds the required test context', () => {
+ expect(job.needs).toEqual(['check-scope']);
+ expect(job.if).toContain('always()');
+ expect(job['runs-on']).toBe('4-core-ubuntu');
+ expect(job['timeout-minutes']).toBe(20);
+ expect(step('Require successful scope classification').run).toContain(
+ 'refusing to skip required work',
+ );
+
+ expect(ci.jobs.test.needs).toContain('registry-contract');
+ const join = ci.jobs.test.steps
+ .map(candidate => candidate.run ?? '')
+ .join('\n');
+ expect(join).toContain('needs.registry-contract.result');
+ expect(join).toContain('needs.registry-contract.result }}" = "success"');
+ });
+
+ it('runs every material step except on the trusted spec-only lane', () => {
+ for (const candidate of job.steps) {
+ if (
+ candidate.name === 'Require successful scope classification' ||
+ candidate.name === 'Skip registry work for spec-only changes'
+ ) {
+ continue;
+ }
+ if (candidate.run || candidate.uses) {
+ expect(candidate.if, candidate.name ?? candidate.uses).toContain(
+ SPEC_FALSE,
+ );
+ }
+ }
+ });
+
+ it('proves production exclusion before generating the canary catalog', () => {
+ const production = step('Verify production excludes compatibility output');
+ expect(production.run).toBe(
+ 'node internal/shadcn-registry/verify-production-gate.mjs',
+ );
+ expect(production.env).toBeUndefined();
+ const generateData = read('apps/docsite/scripts/generate-data.mjs');
+ expect(generateData).toContain('generateShadcnRegistryForTarget({');
+ expect(generateData).not.toMatch(/\bgenerateShadcnRegistry\(\{/);
+
+ const preview = step('Generate and validate the complete preview registry');
+ expect(preview.env.DOCSITE_TARGET).toBe('canary');
+ expect(preview.run).toContain('generate-data.mjs');
+ });
+
+ it('builds every workspace package before exercising local package exports', () => {
+ expect(step('Build registry package exports').run).toBe('pnpm build');
+ });
+
+ it('uses the complete clean-consumer verifier and an exact ShadCN pin', () => {
+ expect(step('Install and build every registry item').run).toBe(
+ 'node internal/shadcn-registry/verify-full-catalog.mjs',
+ );
+ const manifest = JSON.parse(read('apps/docsite/package.json'));
+ expect(manifest.devDependencies.shadcn).toMatch(/^\d+\.\d+\.\d+$/);
+
+ const verifier = read('internal/shadcn-registry/verify-full-catalog.mjs');
+ for (const invariant of [
+ "'add', ...itemPaths",
+ "'--silent'",
+ 'installed different bytes',
+ 'did not install declared dependency',
+ 'alias route',
+ 'duplicate item name',
+ 'must contain exactly one source and one receipt',
+ 'parseRegistryReceipt',
+ 'compileSources(project, sources)',
+ ]) {
+ expect(verifier).toContain(invariant);
+ }
+ expect(runLines()).toContain('verify-full-catalog.mjs');
+ });
+});
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8430331389..865a8fcaf1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -284,21 +284,68 @@ jobs:
- run: pnpm vitest run --project node
if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true'
- # Historical required check name. Both lanes always run (they skip their own
- # steps for lightweight docs, exactly as the single job did), so this asserts
- # success rather than tolerating a skip.
+ # Public registry contract. Generation proves schema, dependency, route-lock,
+ # alias, and release-gating invariants; the final step drives every canonical
+ # item through the exact pinned ShadCN client and compiles every written source.
+ registry-contract:
+ needs: [check-scope]
+ if: ${{ always() && !cancelled() }}
+ runs-on: 4-core-ubuntu
+ timeout-minutes: 20
+ permissions:
+ contents: read
+ steps:
+ - name: Require successful scope classification
+ if: needs.check-scope.result != 'success'
+ run: |
+ echo "Change scope could not be classified; refusing to skip required work."
+ exit 1
+
+ - name: Skip registry work for spec-only changes
+ if: needs.check-scope.outputs.spec_only == 'true'
+ run: echo "Spec-only PR — public registry output cannot change"
+
+ - uses: actions/checkout@v7
+ if: needs.check-scope.outputs.spec_only != 'true'
+
+ - uses: ./.github/actions/setup
+ if: needs.check-scope.outputs.spec_only != 'true'
+
+ - name: Build registry package exports
+ if: needs.check-scope.outputs.spec_only != 'true'
+ run: pnpm build
+
+ - name: Verify production excludes compatibility output
+ if: needs.check-scope.outputs.spec_only != 'true'
+ run: node internal/shadcn-registry/verify-production-gate.mjs
+
+ - name: Generate and validate the complete preview registry
+ if: needs.check-scope.outputs.spec_only != 'true'
+ env:
+ DOCSITE_TARGET: canary
+ run: node apps/docsite/scripts/generate-data.mjs
+
+ - name: Install and build every registry item
+ if: needs.check-scope.outputs.spec_only != 'true'
+ run: node internal/shadcn-registry/verify-full-catalog.mjs
+
+ # Historical required check name. The two Vitest lanes and the public
+ # registry contract always report, so this asserts success rather than
+ # tolerating a skip.
test:
- needs: [test-ui, test-node]
+ needs: [test-ui, test-node, registry-contract]
if: ${{ always() && !cancelled() }}
runs-on: ubuntu-slim
permissions: {}
steps:
- - name: Assert both test lanes succeeded
+ - name: Assert every test gate succeeded
run: |
- echo "test-ui: ${{ needs.test-ui.result }}"
- echo "test-node: ${{ needs.test-node.result }}"
+ echo "test-ui: ${{ needs.test-ui.result }}"
+ echo "test-node: ${{ needs.test-node.result }}"
+ echo "registry-contract: ${{ needs.registry-contract.result }}"
[ "${{ needs.test-ui.result }}" = "success" ] || exit 1
[ "${{ needs.test-node.result }}" = "success" ] || exit 1
+ [ "${{ needs.registry-contract.result }}" = "success" ] || exit 1
# Build storybook + typecheck + analyze components (parallel with test and
# build-sandbox). Uploads the storybook preview and analysis artifacts for
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 086d8b45dc..f8b21f1714 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -31,7 +31,7 @@ import {
buildTypeDefinitionIndex,
collectPropTypeRefs,
} from '../src/lib/typeDefinitions.mjs';
-import {generateShadcnRegistry} from './generate-shadcn-registry.mjs';
+import {generateShadcnRegistryForTarget} from './generate-shadcn-registry.mjs';
import {
blockRegistryIdentity,
resolveShadcnRegistryOrigin,
@@ -410,6 +410,7 @@ function generatePackageRegistry() {
description: raw.description || '',
packagePath: dir,
canaryOnly,
+ peerDependencies: raw.peerDependencies ?? {},
hasReadme,
hasChangelog,
readme,
@@ -428,6 +429,7 @@ export interface PackageMeta {
description: string;
packagePath: string;
canaryOnly: boolean;
+ peerDependencies: Record<string, string>;
hasReadme: boolean;
hasChangelog: boolean;
readme: string | null;
@@ -2217,26 +2219,19 @@ async function main() {
const {templates, templateCount} = await generateTemplateRegistry();
const {docsCount} = await generateDocsRegistry();
const {blogPostCount} = await generateBlogRegistry();
- const shadcnCounts =
- DOCSITE_TARGET === 'canary'
- ? generateShadcnRegistry({
- outDir: path.join(DOCSITE_ROOT, 'public', 'shadcn'),
- packages,
- allComponents,
- blocks,
- templates,
- cliRoot: CLI_ROOT,
- dependencyTag: 'canary',
- externalDependencySpecs: registryExternalDependencySpecs(),
- })
- : null;
+ const shadcnCounts = generateShadcnRegistryForTarget({
+ target: DOCSITE_TARGET,
+ outDir: path.join(DOCSITE_ROOT, 'public', 'shadcn'),
+ packages,
+ allComponents,
+ blocks,
+ templates,
+ cliRoot: CLI_ROOT,
+ dependencyTag: 'canary',
+ externalDependencySpecs: registryExternalDependencySpecs(),
+ });
if (shadcnCounts) {
checkShadcnRouteLock(shadcnCounts.contracts);
- } else {
- fs.rmSync(path.join(DOCSITE_ROOT, 'public', 'shadcn'), {
- recursive: true,
- force: true,
- });
}
// `/r` stays unclaimed for a future Astryx-native registry.
fs.rmSync(path.join(DOCSITE_ROOT, 'public', 'r'), {
diff --git a/apps/docsite/scripts/generate-shadcn-registry.mjs b/apps/docsite/scripts/generate-shadcn-registry.mjs
index 87200b1f3f..e3f32ca8f5 100644
--- a/apps/docsite/scripts/generate-shadcn-registry.mjs
+++ b/apps/docsite/scripts/generate-shadcn-registry.mjs
@@ -19,6 +19,7 @@ import babel from '@babel/core';
import stylexPlugin from '@stylexjs/babel-plugin';
import ts from 'typescript';
import {registryItemSchema, registrySchema} from 'shadcn/schema';
+import {stripCopyrightHeader} from '../../../packages/cli/foundation/text/copyright-header.mjs';
import {
createRegistryReceipt,
registryReceiptTarget,
@@ -85,7 +86,11 @@ function readImportSpecifiers(source, fileName) {
return [...specifiers].sort();
}
-function dependencySpec(packageName, packageDependencies) {
+function dependencySpec(
+ packageName,
+ packageDependencies,
+ fallbackRange = null,
+) {
const spec = packageDependencies.get(packageName);
if (spec) {
return spec;
@@ -93,7 +98,7 @@ function dependencySpec(packageName, packageDependencies) {
if (packageName.startsWith('@astryxdesign/')) {
throw new UnpublishedAstryxDependencyError(packageName);
}
- return packageName;
+ return fallbackRange ? `${packageName}@${fallbackRange}` : packageName;
}
function precompileStylexSource(source, fileName) {
@@ -133,7 +138,49 @@ function precompileStylexSource(source, fileName) {
};
}
-function dependenciesForSource(source, fileName, packageDependencies) {
+function dependenciesForPackages(
+ packageNames,
+ packageDependencies,
+ packagePeerDependencies,
+) {
+ const dependencies = new Set();
+ const visited = new Set();
+ const queue = [
+ ...packageNames.map(name => ({name, range: null})),
+ {name: '@astryxdesign/core', range: null},
+ {name: '@stylexjs/stylex', range: null},
+ ];
+
+ while (queue.length > 0) {
+ const {name, range} = queue.shift();
+ if (
+ visited.has(name) ||
+ name === 'react' ||
+ name.startsWith('react/') ||
+ name === 'react-dom' ||
+ name.startsWith('react-dom/')
+ ) {
+ continue;
+ }
+ visited.add(name);
+ dependencies.add(dependencySpec(name, packageDependencies, range));
+
+ for (const [peerName, peerRange] of Object.entries(
+ packagePeerDependencies.get(name) ?? {},
+ )) {
+ queue.push({name: peerName, range: peerRange});
+ }
+ }
+
+ return [...dependencies].sort();
+}
+
+function dependenciesForSource(
+ source,
+ fileName,
+ packageDependencies,
+ packagePeerDependencies,
+) {
const packages = new Set();
for (const specifier of readImportSpecifiers(source, fileName)) {
if (specifier.startsWith('.')) {
@@ -153,22 +200,19 @@ function dependenciesForSource(source, fileName, packageDependencies) {
}
packages.add(packageNameFromSpecifier(specifier));
}
- return [...packages]
- .map(packageName => dependencySpec(packageName, packageDependencies))
- .sort();
-}
-
-function withCoreDependency(dependencies, packageDependencies) {
- return [
- ...new Set([
- ...dependencies,
- dependencySpec('@astryxdesign/core', packageDependencies),
- dependencySpec('@stylexjs/stylex', packageDependencies),
- ]),
- ].sort();
+ return dependenciesForPackages(
+ [...packages],
+ packageDependencies,
+ packagePeerDependencies,
+ );
}
-function componentItem(packageName, component, packageDependencies) {
+function componentItem(
+ packageName,
+ component,
+ packageDependencies,
+ packagePeerDependencies,
+) {
if (!component.importPath) {
throw new Error(
`${packageName}/${component.name} has no public import path`,
@@ -195,9 +239,10 @@ function componentItem(packageName, component, packageDependencies) {
component.description ||
`Public ${isHook ? 'hook' : 'component'} entry for ${component.name}.`,
author: 'Astryx',
- dependencies: withCoreDependency(
- [dependencySpec(packageName, packageDependencies)],
+ dependencies: dependenciesForPackages(
+ [packageName],
packageDependencies,
+ packagePeerDependencies,
),
css: ASTRYX_CSS,
files: [
@@ -262,7 +307,13 @@ function withCompositionReceipt(item, identity, sourceVersion) {
};
}
-function blockItem(block, packageDependencies, cliRoot, sourceVersion) {
+function blockItem(
+ block,
+ packageDependencies,
+ packagePeerDependencies,
+ cliRoot,
+ sourceVersion,
+) {
const identity = blockRegistryIdentity(
block.name,
block.exampleFor,
@@ -279,7 +330,10 @@ function blockItem(block, packageDependencies, cliRoot, sourceVersion) {
block.category,
`${block.dirName}.tsx`,
);
- const compiled = precompileStylexSource(block.source, fileName);
+ const compiled = precompileStylexSource(
+ stripCopyrightHeader(block.source),
+ fileName,
+ );
return withCompositionReceipt(
{
$schema: REGISTRY_ITEM_SCHEMA,
@@ -288,9 +342,11 @@ function blockItem(block, packageDependencies, cliRoot, sourceVersion) {
title: block.displayName || block.name,
description: block.description || `Astryx ${kind}: ${block.name}.`,
author: 'Astryx',
- dependencies: withCoreDependency(
- dependenciesForSource(compiled.source, fileName, packageDependencies),
+ dependencies: dependenciesForSource(
+ compiled.source,
+ fileName,
packageDependencies,
+ packagePeerDependencies,
),
css: ASTRYX_CSS,
files: [
@@ -316,7 +372,13 @@ function blockItem(block, packageDependencies, cliRoot, sourceVersion) {
);
}
-function pageItem(template, packageDependencies, cliRoot, sourceVersion) {
+function pageItem(
+ template,
+ packageDependencies,
+ packagePeerDependencies,
+ cliRoot,
+ sourceVersion,
+) {
const identity = pageRegistryIdentity(template.slug, template.registry);
const itemName = identity.name;
const fileName = path.join(
@@ -327,7 +389,10 @@ function pageItem(template, packageDependencies, cliRoot, sourceVersion) {
template.slug,
'page.tsx',
);
- const compiled = precompileStylexSource(template.source, fileName);
+ const compiled = precompileStylexSource(
+ stripCopyrightHeader(template.source),
+ fileName,
+ );
return withCompositionReceipt(
{
$schema: REGISTRY_ITEM_SCHEMA,
@@ -336,9 +401,11 @@ function pageItem(template, packageDependencies, cliRoot, sourceVersion) {
title: template.name,
description: template.description || `Astryx page: ${template.name}.`,
author: 'Astryx',
- dependencies: withCoreDependency(
- dependenciesForSource(compiled.source, fileName, packageDependencies),
+ dependencies: dependenciesForSource(
+ compiled.source,
+ fileName,
packageDependencies,
+ packagePeerDependencies,
),
css: ASTRYX_CSS,
files: [
@@ -426,6 +493,9 @@ export function buildShadcnRegistry({
]),
...Object.entries(externalDependencySpecs),
]);
+ const packagePeerDependencies = new Map(
+ packages.map(pkg => [pkg.name, pkg.peerDependencies ?? {}]),
+ );
const componentEntries = Object.entries(allComponents);
const skippedComponents = componentEntries
.filter(([packageName]) => !packageDependencies.has(packageName))
@@ -434,7 +504,12 @@ export function buildShadcnRegistry({
.filter(([packageName]) => packageDependencies.has(packageName))
.flatMap(([packageName, components]) =>
components.map(component =>
- componentItem(packageName, component, packageDependencies),
+ componentItem(
+ packageName,
+ component,
+ packageDependencies,
+ packagePeerDependencies,
+ ),
),
)
.sort((a, b) => a.name.localeCompare(b.name));
@@ -443,7 +518,13 @@ export function buildShadcnRegistry({
for (const block of blocks) {
try {
blockItems.push(
- blockItem(block, packageDependencies, cliRoot, sourceVersion),
+ blockItem(
+ block,
+ packageDependencies,
+ packagePeerDependencies,
+ cliRoot,
+ sourceVersion,
+ ),
);
} catch (error) {
if (error instanceof UnpublishedAstryxDependencyError) {
@@ -460,7 +541,13 @@ export function buildShadcnRegistry({
for (const template of templates) {
try {
pageItems.push(
- pageItem(template, packageDependencies, cliRoot, sourceVersion),
+ pageItem(
+ template,
+ packageDependencies,
+ packagePeerDependencies,
+ cliRoot,
+ sourceVersion,
+ ),
);
} catch (error) {
if (error instanceof UnpublishedAstryxDependencyError) {
@@ -520,6 +607,14 @@ function writeJson(filePath, value) {
fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
}
+export function generateShadcnRegistryForTarget({target, outDir, ...options}) {
+ if (target !== 'canary') {
+ fs.rmSync(outDir, {recursive: true, force: true});
+ return null;
+ }
+ return generateShadcnRegistry({outDir, ...options});
+}
+
export function generateShadcnRegistry({
outDir,
packages,
diff --git a/docs/specs/AST-026/spec.md b/docs/specs/AST-026/spec.md
index 30c6fafd54..ccb828e016 100644
--- a/docs/specs/AST-026/spec.md
+++ b/docs/specs/AST-026/spec.md
@@ -86,6 +86,11 @@ launch gate for the production endpoint and announcement.
installed Astryx release, auto-update an unchanged file, three-way merge
edits, leave the original untouched when edits conflict, and never recreate a
deleted or moved file.
+- **FR10 — Required full-catalog CI.** Required pull-request CI MUST generate
+ the complete preview catalog, reject production output before launch, install
+ every canonical item through the pinned shadcn client, verify every route and
+ exact written file, and compile every installed source against the current
+ Astryx package exports.
- **IR1 — Generated from current sources.** Registry output MUST come from the
existing docsite and CLI catalogs, never a parallel handwritten item list.
- **IR2 — Build-time static output.** The docsite build MUST generate static JSON
@@ -94,10 +99,11 @@ launch gate for the production endpoint and announcement.
- **IR3 — Failure is loud.** Missing source, duplicate names, invalid schemas,
unresolved package versions, escaping relative imports, and stale generated
output MUST fail generation or verification.
-- **IR4 — End-to-end evidence.** Verification MUST install representative
- component, showcase, block, and page items into a clean shadcn-style app and
- build that app. The full catalog MUST receive schema, uniqueness, dependency,
- and source-boundary checks.
+- **IR4 — End-to-end evidence.** Required verification MUST install every
+ canonical component, hook, showcase, example, block, and page into a clean
+ shadcn-style app through the pinned stock client, verify exact written bytes
+ and declared dependencies, and compile every written source file. Alias
+ routes MUST resolve to the same canonical item bytes.
- **IR5 — Stable route contract.** Generated item names and canonical paths MUST
match the reviewed route lock. Display-name edits MUST NOT change them. An
intentional rename MUST retain old paths through `registry.aliases` unless a
@@ -121,30 +127,29 @@ showcases and examples, blocks, pages, package versions, and source. The
compatibility layer adds a serializer over that existing catalog rather than a
second discovery system.
-The current catalog generates 970 items. Its 702 copied compositions each carry
-a validated adjacent receipt. Prior evidence, before receipts were added,
-installed all 921 then-generated entries through shadcn 4.19.0 into a clean Vite
-application, wrote every component, hook, block, and page file with zero install
-failures, and compiled all 6,620 imported modules in one build. Fourteen
-compositions that author local StyleX are precompiled to compiler-free JSX during
-generation; all other composition source stays typed TSX. Component
-implementation copying failed because private imports and uncompiled StyleX
-crossed the package boundary; FR2 avoids that path by installing the package and
-creating a public re-export only.
+The current catalog generates 970 items. Its 700 copied compositions each carry
+an adjacent receipt whose base matches the exact bytes stock shadcn writes.
+Required CI installs all 970 entries through shadcn 4.19.0 into one clean
+consumer, verifies all 1,670 written source and receipt files, and compiles all
+970 source entry points. Fourteen compositions that author local StyleX are
+precompiled to compiler-free JSX during generation; all other composition
+source stays typed TSX. Component implementation copying failed because private
+imports and uncompiled StyleX crossed the package boundary; FR2 avoids that
+path by installing the package and creating a public re-export only.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
-| FR1, FR5 | shadcn schema validation and deterministic snapshot | component, showcase, example, block, page | Unknown type, duplicate name, or unstable output fails |
-| FR2 | clean consumer install plus source inspection | Core component, hook, non-Core package | Implementation source or private import fails |
-| FR3, IR1 | reconcile registry counts and names with generated docsite catalogs | visible and hidden entries, grouped families | Missing or extra catalog entry fails |
-| FR4, IR3 | dependency extraction and relative-import audit | heroicons, recharts, StyleX import, page source | Escaping import or undeclared package fails |
-| FR6 | raw JSON and shadcn parse tests | optional `astryx` metadata present | shadcn install changes or Astryx metadata becomes required |
-| FR7 | docsite tests and copy-button interaction | component, block, page, compatibility guide | Command is absent, stale, or misstates copy behavior |
-| FR8 | canary preview plus production-target assertion | preview and released package dependencies | Production enables before the upgrade gate passes |
-| FR9 | receipt mutation tests plus stock ShadCN install | pristine, edited, conflicting, missing, aliased | User source is overwritten or an old route stops resolving |
-| IR4 | clean shadcn-style fixture install, build, and Chrome screenshot | one of each item kind; light and dark | Install, build, or render fails |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
+| FR1, FR5 | shadcn schema validation and deterministic snapshot | component, showcase, example, block, page | Unknown type, duplicate name, or unstable output fails |
+| FR2 | clean consumer install plus source inspection | Core component, hook, non-Core package | Implementation source or private import fails |
+| FR3, IR1 | reconcile registry counts and names with generated docsite catalogs | visible and hidden entries, grouped families | Missing or extra catalog entry fails |
+| FR4, IR3 | dependency extraction and relative-import audit | heroicons, recharts, StyleX import, page source | Escaping import or undeclared package fails |
+| FR6 | raw JSON and shadcn parse tests | optional `astryx` metadata present | shadcn install changes or Astryx metadata becomes required |
+| FR7 | docsite tests and copy-button interaction | component, block, page, compatibility guide | Command is absent, stale, or misstates copy behavior |
+| FR8 | canary preview plus production-target assertion | preview and released package dependencies | Production enables before the upgrade gate passes |
+| FR9 | receipt mutation tests plus stock ShadCN install | pristine, edited, conflicting, missing, aliased | User source is overwritten or an old route stops resolving |
+| FR10, IR4 | required full-catalog clean-consumer install and build | every canonical item, route, dependency, target | Any item fails to install, match its receipt, or compile |
## Decision log
@@ -226,6 +231,25 @@ user edits the file. Also rejected: rebuilding the latest composition from raw
CLI template assets at upgrade time. StyleX-precompiled registry items require
the registry's compiled bytes.
+### DEC-7 — Gate every registry item through one clean consumer
+
+**Reference:** `spec:AST-026/DEC-7`
+**Decider:** `josephfarina`, `2026-09-10`
+
+Required pull-request CI proves the release-channel selector removes compatibility
+output for production, then passes every canonical preview item to the pinned
+shadcn client in one clean consumer. The consumer replaces Astryx package pins
+with the current local package builds so a new component can prove its exports
+before that version exists on npm; all third-party dependencies retain the
+versions declared by the generated catalog. CI compares every written file with
+its registry bytes and compiles every source while resolving Astryx package
+exports.
+
+Rejected: one client process per item. It repeats dependency installation
+hundreds of times without adding protocol coverage. Also rejected: validating
+only representative items. A source or target defect can be unique to any one
+of the generated compositions.
+
## Open questions
- **OQ1 — Catalog visibility.** (`human-design`) Should hidden or not-ready
diff --git a/internal/shadcn-registry/generate-shadcn-registry.test.mjs b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
index 84767d3fdb..d372d3d17d 100644
--- a/internal/shadcn-registry/generate-shadcn-registry.test.mjs
+++ b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
@@ -29,6 +29,7 @@ import {
import {
buildShadcnRegistry,
generateShadcnRegistry,
+ generateShadcnRegistryForTarget,
} from '../../apps/docsite/scripts/generate-shadcn-registry.mjs';
import {
blockRegistryIdentity,
@@ -297,6 +298,22 @@ describe('buildShadcnRegistry', () => {
}
});
+ it('removes stale compatibility output for non-canary targets', () => {
+ const root = mkdtempSync(path.join(tmpdir(), 'astryx-shadcn-production-'));
+ const outDir = path.join(root, 'shadcn');
+ try {
+ mkdirSync(outDir, {recursive: true});
+ writeFileSync(path.join(outDir, 'stale.json'), '{}\n');
+
+ expect(
+ generateShadcnRegistryForTarget({target: 'latest', outDir}),
+ ).toBeNull();
+ expect(existsSync(outDir)).toBe(false);
+ } finally {
+ rmSync(root, {recursive: true, force: true});
+ }
+ });
+
it('creates a first-class standalone block item', () => {
const standalone = {
...fixture().blocks[0],
@@ -359,7 +376,22 @@ describe('buildShadcnRegistry', () => {
const project = mkdtempSync(path.join(tmpdir(), 'astryx-shadcn-receipt-'));
try {
writeConsumerProject(project);
- const {items} = buildShadcnRegistry(fixture());
+ const base = fixture();
+ const {items} = buildShadcnRegistry(
+ fixture({
+ blocks: [
+ {
+ ...base.blocks[0],
+ source:
+ '// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n' +
+ "'use client';\n\n" +
+ '// Keep this consumer guidance.\n' +
+ "import {Button} from '@astryxdesign/core/Button';\n" +
+ 'export default function ButtonShowcase() { return <Button label="Save" />; }\n',
+ },
+ ],
+ }),
+ );
const block = items.find(
item => item.name === 'showcase-button-variants',
);
@@ -397,6 +429,37 @@ describe('buildShadcnRegistry', () => {
),
),
).toBe(true);
+ const installedSource = readFileSync(
+ path.join(
+ project,
+ 'src',
+ 'components',
+ 'astryx',
+ 'showcases',
+ 'ButtonShowcase.tsx',
+ ),
+ 'utf8',
+ );
+ const installedReceipt = parseRegistryReceipt(
+ JSON.parse(
+ readFileSync(
+ path.join(
+ project,
+ 'src',
+ 'components',
+ 'astryx',
+ 'showcases',
+ '.astryx',
+ 'showcase-button-variants.json',
+ ),
+ 'utf8',
+ ),
+ ),
+ );
+ expect(block.files[0].content).not.toContain('Copyright (c) Meta');
+ expect(installedSource).toBe(block.files[0].content);
+ expect(installedReceipt.files[0].content).toBe(installedSource);
+ expect(installedSource).toContain('// Keep this consumer guidance.');
} finally {
rmSync(project, {recursive: true, force: true});
}
@@ -508,6 +571,53 @@ describe('buildShadcnRegistry', () => {
]);
});
+ it('installs non-React peer dependencies for package-backed entries', () => {
+ const base = fixture();
+ const {items} = buildShadcnRegistry(
+ fixture({
+ packages: [
+ ...base.packages,
+ {
+ name: '@astryxdesign/richtext',
+ version: '0.1.9',
+ peerDependencies: {
+ '@astryxdesign/core': '0.5.2',
+ '@lexical/react': '^0.46.0',
+ '@stylexjs/stylex': '>=0.10.0',
+ lexical: '^0.46.0',
+ react: '>=19.0.0',
+ 'react-dom': '>=19.0.0',
+ },
+ },
+ ],
+ allComponents: {
+ ...base.allComponents,
+ '@astryxdesign/richtext': [
+ {
+ name: 'RichTextEditor',
+ displayName: 'Rich Text Editor',
+ importPath: '@astryxdesign/richtext',
+ hidden: false,
+ params: null,
+ },
+ ],
+ },
+ dependencyTag: 'canary',
+ }),
+ );
+ const component = items.find(
+ item => item.name === 'component-richtext-rich-text-editor',
+ );
+
+ expect(component.dependencies).toEqual([
+ '@astryxdesign/core@canary',
+ '@astryxdesign/richtext@canary',
+ '@lexical/react@^0.46.0',
+ '@stylexjs/[email protected]',
+ 'lexical@^0.46.0',
+ ]);
+ });
+
it('uses the shadcn page-file workaround without changing item semantics', () => {
const {items} = buildShadcnRegistry(fixture());
const page = items.find(item => item.name === 'template-dashboard');
@@ -670,13 +780,16 @@ describe('buildShadcnRegistry', () => {
dependencyTag: 'canary',
});
const component = items.find(item => item.name === 'component-button');
- const showcase = items.find(item => item.name === 'showcase-button-variants');
+ const showcase = items.find(
+ item => item.name === 'showcase-button-variants',
+ );
expect(component.dependencies).toEqual([
'@astryxdesign/core@canary',
'@stylexjs/[email protected]',
]);
expect(
- parseRegistryReceipt(JSON.parse(showcase.files[1].content)).source.version,
+ parseRegistryReceipt(JSON.parse(showcase.files[1].content)).source
+ .version,
).toBe('canary');
});
diff --git a/internal/shadcn-registry/verify-full-catalog.mjs b/internal/shadcn-registry/verify-full-catalog.mjs
new file mode 100644
index 0000000000..663c0f91b9
--- /dev/null
+++ b/internal/shadcn-registry/verify-full-catalog.mjs
@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file verify-full-catalog.mjs
+ * @description Installs every generated Astryx registry item through the pinned
+ * ShadCN client, verifies exact written bytes and dependencies, then compiles
+ * every installed source file against the current Astryx package exports.
+ * @input A generated canary registry under apps/docsite/public/shadcn.
+ * @output A clean-consumer proof for every canonical item and alias route.
+ * @position Required CI contract for the public ShadCN compatibility surface.
+ */
+
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import {createRequire} from 'node:module';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {build} from 'esbuild';
+
+import {parseRegistryReceipt} from '../../packages/cli/authoring/shadcn/receipt.mjs';
+import {expandWorkspaceDirs} from '../../scripts/lib/workspace-globs.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const REGISTRY_DIR = path.join(
+ REPO_ROOT,
+ 'apps',
+ 'docsite',
+ 'public',
+ 'shadcn',
+);
+const docsiteRequire = createRequire(
+ path.join(REPO_ROOT, 'apps', 'docsite', 'package.json'),
+);
+const SHADCN_BIN = docsiteRequire.resolve('shadcn');
+const KEEP_TEMP = process.env.ASTRYX_KEEP_SHADCN_MATRIX === '1';
+const MAX_COMMAND_OUTPUT = 16 * 1024 * 1024;
+const COPIED_KINDS = new Set(['showcase', 'example', 'block', 'page']);
+
+function fail(message) {
+ throw new Error(`ShadCN registry CI: ${message}`);
+}
+
+function readJSON(file) {
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function resolveInside(root, relative, label) {
+ if (typeof relative !== 'string' || path.isAbsolute(relative)) {
+ fail(`${label} is not a safe relative path: ${String(relative)}`);
+ }
+ const resolvedRoot = path.resolve(root);
+ const resolved = path.resolve(resolvedRoot, relative);
+ if (
+ resolved !== resolvedRoot &&
+ !resolved.startsWith(`${resolvedRoot}${path.sep}`)
+ ) {
+ fail(`${label} escapes its root: ${relative}`);
+ }
+ return resolved;
+}
+
+function packageName(spec) {
+ if (spec.startsWith('@')) {
+ const slash = spec.indexOf('/');
+ const version = spec.indexOf('@', slash);
+ return version === -1 ? spec : spec.slice(0, version);
+ }
+ const version = spec.indexOf('@');
+ return version === -1 ? spec : spec.slice(0, version);
+}
+
+function localPackageDirs() {
+ const result = new Map();
+ for (const directory of expandWorkspaceDirs(REPO_ROOT)) {
+ const manifestPath = path.join(directory, 'package.json');
+ if (!fs.existsSync(manifestPath)) continue;
+ const manifest = readJSON(manifestPath);
+ if (typeof manifest.name === 'string') {
+ result.set(manifest.name, directory);
+ }
+ }
+ return result;
+}
+
+function verifyItemFileShape(item) {
+ const receipts = item.files.filter(
+ file => file.type === 'registry:file' && file.target.includes('/.astryx/'),
+ );
+ const sources = item.files.filter(file => !receipts.includes(file));
+ const kind = item.astryx?.kind;
+
+ if (COPIED_KINDS.has(kind)) {
+ if (
+ sources.length !== 1 ||
+ receipts.length !== 1 ||
+ item.files.length !== 2
+ ) {
+ fail(`${item.name} must contain exactly one source and one receipt`);
+ }
+ const source = sources[0];
+ const receiptFile = receipts[0];
+ const expectedReceiptTarget = path.posix.join(
+ path.posix.dirname(source.target),
+ '.astryx',
+ `${item.name}.json`,
+ );
+ if (receiptFile.target !== expectedReceiptTarget) {
+ fail(`${item.name} receipt is not adjacent to its source`);
+ }
+
+ let receipt;
+ try {
+ receipt = parseRegistryReceipt(JSON.parse(receiptFile.content));
+ } catch (error) {
+ fail(`${item.name} has an invalid receipt: ${error.message}`);
+ }
+ if (
+ receipt.item.name !== item.name ||
+ receipt.item.path !== item.astryx.path ||
+ receipt.item.kind !== kind ||
+ receipt.files.length !== 1 ||
+ receipt.files[0].registryPath !== source.path ||
+ receipt.files[0].registryTarget !== source.target ||
+ receipt.files[0].content !== source.content
+ ) {
+ fail(`${item.name} receipt does not describe its installed source`);
+ }
+ return;
+ }
+
+ if (
+ (kind === 'component' || kind === 'hook') &&
+ sources.length === 1 &&
+ receipts.length === 0 &&
+ item.files.length === 1
+ ) {
+ return;
+ }
+
+ fail(`${item.name} has an unsupported ${String(kind)} file shape`);
+}
+
+function loadCatalog() {
+ const indexPath = path.join(REGISTRY_DIR, 'registry.json');
+ if (!fs.existsSync(indexPath)) {
+ fail(
+ `missing ${path.relative(REPO_ROOT, indexPath)}; generate the canary docsite data first`,
+ );
+ }
+
+ const index = readJSON(indexPath);
+ if (!Array.isArray(index.items) || index.items.length === 0) {
+ fail('registry.json contains no items');
+ }
+
+ const names = new Map();
+ const routes = new Map();
+ const targets = new Map();
+ const items = [];
+
+ for (const summary of index.items) {
+ const name = summary.name;
+ const registryPath = summary.astryx?.path;
+ if (typeof name !== 'string' || typeof registryPath !== 'string') {
+ fail('registry.json contains an item without a stable name and path');
+ }
+ if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+ fail(`item name is not safe: ${name}`);
+ }
+ if (names.has(name)) {
+ fail(`duplicate item name ${name}`);
+ }
+ names.set(name, registryPath);
+
+ const canonicalFile = resolveInside(
+ REGISTRY_DIR,
+ `${registryPath}.json`,
+ `${name} canonical route`,
+ );
+ if (!fs.existsSync(canonicalFile)) {
+ fail(`${name} is missing canonical route ${registryPath}.json`);
+ }
+ const canonicalBytes = fs.readFileSync(canonicalFile, 'utf8');
+ const item = JSON.parse(canonicalBytes);
+ if (item.name !== name || item.astryx?.path !== registryPath) {
+ fail(`${registryPath}.json does not match its registry.json identity`);
+ }
+
+ for (const route of [registryPath, ...(item.astryx?.aliases ?? [])]) {
+ const prior = routes.get(route);
+ if (prior != null) {
+ fail(`route ${route}.json is claimed by both ${prior} and ${name}`);
+ }
+ routes.set(route, name);
+ const routeFile = resolveInside(
+ REGISTRY_DIR,
+ `${route}.json`,
+ `${name} route`,
+ );
+ if (!fs.existsSync(routeFile)) {
+ fail(`${name} is missing route ${route}.json`);
+ }
+ if (fs.readFileSync(routeFile, 'utf8') !== canonicalBytes) {
+ fail(`alias route ${route}.json drifted from canonical item ${name}`);
+ }
+ }
+
+ if (!Array.isArray(item.files) || item.files.length === 0) {
+ fail(`${name} has no installable files`);
+ }
+ for (const file of item.files) {
+ if (typeof file.target !== 'string' || typeof file.content !== 'string') {
+ fail(`${name} has a file without a target and content`);
+ }
+ resolveInside('/registry-source', file.path, `${name} source path`);
+ resolveInside('/consumer', file.target, `${name} target`);
+ const prior = targets.get(file.target);
+ if (prior != null) {
+ fail(`target ${file.target} is written by both ${prior} and ${name}`);
+ }
+ targets.set(file.target, name);
+ }
+ verifyItemFileShape(item);
+ items.push(item);
+ }
+
+ return {items, routeCount: routes.size, targetCount: targets.size};
+}
+
+function writeConsumer(project, items, packageDirs) {
+ const rootManifest = readJSON(path.join(REPO_ROOT, 'package.json'));
+ const itemDirectory = path.join(project, 'items');
+ fs.mkdirSync(path.join(project, 'src'), {recursive: true});
+ fs.mkdirSync(itemDirectory, {recursive: true});
+
+ fs.writeFileSync(
+ path.join(project, 'package.json'),
+ `${JSON.stringify(
+ {
+ name: 'astryx-shadcn-registry-ci',
+ private: true,
+ version: '0.0.0',
+ packageManager: rootManifest.packageManager,
+ dependencies: {
+ react: rootManifest.devDependencies.react,
+ 'react-dom': rootManifest.devDependencies['react-dom'],
+ },
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ // Every dependency is pinned by generated registry data. The consumer is
+ // ephemeral, and local Astryx packages need their checked-in install hooks.
+ fs.writeFileSync(
+ path.join(project, 'pnpm-workspace.yaml'),
+ 'packages: []\ndangerouslyAllowAllBuilds: true\n',
+ );
+ fs.writeFileSync(
+ path.join(project, 'tsconfig.json'),
+ `${JSON.stringify(
+ {
+ compilerOptions: {
+ baseUrl: '.',
+ jsx: 'react-jsx',
+ module: 'ESNext',
+ moduleResolution: 'Bundler',
+ paths: {'@/*': ['./src/*']},
+ target: 'ES2022',
+ },
+ include: ['src'],
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ fs.writeFileSync(
+ path.join(project, 'components.json'),
+ `${JSON.stringify(
+ {
+ $schema: 'https://ui.shadcn.com/schema.json',
+ style: 'nova',
+ rsc: false,
+ tsx: true,
+ tailwind: {
+ config: '',
+ css: 'src/index.css',
+ baseColor: '',
+ cssVariables: true,
+ prefix: '',
+ },
+ aliases: {
+ components: '@/components',
+ hooks: '@/hooks',
+ lib: '@/lib',
+ ui: '@/components/ui',
+ utils: '@/lib/utils',
+ },
+ iconLibrary: 'lucide',
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ fs.writeFileSync(path.join(project, 'src', 'index.css'), '');
+
+ const itemPaths = [];
+ const dependencyNames = new Set();
+ for (const item of items) {
+ const installItem = structuredClone(item);
+ installItem.dependencies = (installItem.dependencies ?? []).map(spec => {
+ const name = packageName(spec);
+ dependencyNames.add(name);
+ if (!name.startsWith('@astryxdesign/')) return spec;
+ const directory = packageDirs.get(name);
+ if (directory == null) {
+ fail(`${item.name} depends on unresolved workspace package ${name}`);
+ }
+ return `${name}@file:${directory}`;
+ });
+ const itemPath = resolveInside(
+ itemDirectory,
+ `${item.name}.json`,
+ `${item.name} temporary item`,
+ );
+ fs.writeFileSync(itemPath, JSON.stringify(installItem));
+ itemPaths.push(itemPath);
+ }
+
+ return {dependencyNames, itemPaths};
+}
+
+function runShadcn(project, itemPaths) {
+ if (!fs.existsSync(SHADCN_BIN)) {
+ fail('the pinned ShadCN binary is not installed');
+ }
+ const result = spawnSync(
+ SHADCN_BIN,
+ ['add', ...itemPaths, '--yes', '--overwrite', '--silent'],
+ {
+ cwd: project,
+ encoding: 'utf8',
+ env: {...process.env, CI: 'true'},
+ maxBuffer: MAX_COMMAND_OUTPUT,
+ timeout: 10 * 60_000,
+ },
+ );
+ if (result.error != null) {
+ fail(`could not run the pinned ShadCN client: ${result.error.message}`);
+ }
+ if (result.status !== 0) {
+ process.stderr.write(result.stdout ?? '');
+ process.stderr.write(result.stderr ?? '');
+ fail(`pinned ShadCN exited ${result.status}`);
+ }
+}
+
+function verifyInstall(project, items, dependencyNames) {
+ const sources = [];
+ let installedFiles = 0;
+
+ for (const item of items) {
+ for (const file of item.files) {
+ const installed = resolveInside(
+ path.join(project, 'src'),
+ file.target,
+ `${item.name} installed target`,
+ );
+ if (!fs.existsSync(installed)) {
+ fail(`${item.name} did not install ${file.target}`);
+ }
+ const actual = fs.readFileSync(installed, 'utf8');
+ if (actual !== file.content) {
+ fail(
+ `${item.name} installed different bytes at ${file.target}; generated content must match stock ShadCN output`,
+ );
+ }
+ installedFiles += 1;
+ if (!file.target.includes('/.astryx/')) {
+ sources.push(installed);
+ }
+ }
+ }
+
+ const manifest = readJSON(path.join(project, 'package.json'));
+ const installedDependencies = new Set([
+ ...Object.keys(manifest.dependencies ?? {}),
+ ...Object.keys(manifest.devDependencies ?? {}),
+ ]);
+ for (const dependency of dependencyNames) {
+ if (!installedDependencies.has(dependency)) {
+ fail(`pinned ShadCN did not install declared dependency ${dependency}`);
+ }
+ }
+
+ const css = fs.readFileSync(path.join(project, 'src', 'index.css'), 'utf8');
+ for (const specifier of [
+ '@astryxdesign/core/reset.css',
+ '@astryxdesign/core/astryx.css',
+ ]) {
+ if (!css.includes(specifier)) {
+ fail(`pinned ShadCN did not install required CSS import ${specifier}`);
+ }
+ }
+
+ return {installedFiles, sources};
+}
+
+async function compileSources(project, sources) {
+ await build({
+ absWorkingDir: project,
+ bundle: true,
+ entryPoints: sources,
+ format: 'esm',
+ jsx: 'automatic',
+ logLevel: 'warning',
+ outdir: path.join(project, 'dist'),
+ platform: 'browser',
+ splitting: true,
+ target: 'es2022',
+ });
+}
+
+async function main() {
+ const startedAt = Date.now();
+ const catalog = loadCatalog();
+ const packageDirs = localPackageDirs();
+ const project = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'astryx-shadcn-registry-ci-'),
+ );
+
+ try {
+ const {dependencyNames, itemPaths} = writeConsumer(
+ project,
+ catalog.items,
+ packageDirs,
+ );
+ runShadcn(project, itemPaths);
+ const {installedFiles, sources} = verifyInstall(
+ project,
+ catalog.items,
+ dependencyNames,
+ );
+ await compileSources(project, sources);
+
+ const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+ console.log(
+ `Verified ${catalog.items.length} items, ${catalog.routeCount} routes, ` +
+ `${installedFiles} installed files, and ${sources.length} compiled sources in ${seconds}s.`,
+ );
+ } finally {
+ if (KEEP_TEMP) {
+ console.log(`Kept clean consumer at ${project}`);
+ } else {
+ fs.rmSync(project, {recursive: true, force: true});
+ }
+ }
+}
+
+main().catch(error => {
+ console.error(error);
+ process.exitCode = 1;
+});
diff --git a/internal/shadcn-registry/verify-production-gate.mjs b/internal/shadcn-registry/verify-production-gate.mjs
new file mode 100644
index 0000000000..1bfdc522cd
--- /dev/null
+++ b/internal/shadcn-registry/verify-production-gate.mjs
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file verify-production-gate.mjs
+ * @description Proves a non-canary docsite target removes stale ShadCN output
+ * without downloading the currently published package catalog.
+ * @input The target-aware registry generator used by generate-data.mjs.
+ * @output A network-free assertion that production cannot expose `/shadcn`.
+ * @position Required CI guard for the staged compatibility launch.
+ */
+
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import {generateShadcnRegistryForTarget} from '../../apps/docsite/scripts/generate-shadcn-registry.mjs';
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-shadcn-gate-'));
+const outDir = path.join(root, 'shadcn');
+
+try {
+ fs.mkdirSync(outDir, {recursive: true});
+ fs.writeFileSync(path.join(outDir, 'stale.json'), '{}\n');
+
+ const result = generateShadcnRegistryForTarget({
+ target: 'latest',
+ outDir,
+ });
+
+ assert.equal(result, null);
+ assert.equal(fs.existsSync(outDir), false);
+ console.log('Verified production excludes ShadCN compatibility output.');
+} finally {
+ fs.rmSync(root, {recursive: true, force: true});
+}
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastAction.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastAction.tsx
index 4e813104ca..367cccec40 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastAction.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastAction.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
import {Button} from '@astryxdesign/core/Button';
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastDeduplication.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastDeduplication.tsx
index ad9b40fb5e..0272e66af6 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastDeduplication.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastDeduplication.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
import {Button} from '@astryxdesign/core/Button';
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastDismiss.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastDismiss.tsx
index 098fa8c9ce..cd0934f184 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastDismiss.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastDismiss.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {useRef} from 'react';
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastShowcase.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastShowcase.tsx
index 6fd5115735..5e43480ee7 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastShowcase.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastShowcase.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
import {Button} from '@astryxdesign/core/Button';
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastStacking.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastStacking.tsx
index deaf0a155c..7ee1bb34c4 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastStacking.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastStacking.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {useRef} from 'react';
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
diff --git a/packages/cli/assets/templates/blocks/components/Toast/ToastTypes.tsx b/packages/cli/assets/templates/blocks/components/Toast/ToastTypes.tsx
index 60dbb5a08c..3f70d2953e 100644
--- a/packages/cli/assets/templates/blocks/components/Toast/ToastTypes.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toast/ToastTypes.tsx
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
'use client';
+// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
+
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
import {Button} from '@astryxdesign/core/Button';