@astryxdesign/cli 0.1.6-canary.eb549c8 → 0.1.6-canary.eba4f34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.eb549c8",
+  "version": "0.1.6-canary.eba4f34",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,10 +75,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.eb549c8",
-    "@astryxdesign/core": "0.1.6-canary.eb549c8",
-    "@astryxdesign/lab": "0.1.6-canary.eb549c8",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.eb549c8",
+    "@astryxdesign/charts": "0.1.6-canary.eba4f34",
+    "@astryxdesign/core": "0.1.6-canary.eba4f34",
+    "@astryxdesign/lab": "0.1.6-canary.eba4f34",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eba4f34",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.eb549c8",
-    "@astryxdesign/core": "0.1.6-canary.eb549c8",
-    "@astryxdesign/lab": "0.1.6-canary.eb549c8",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.eb549c8",
+    "@astryxdesign/charts": "0.1.6-canary.eba4f34",
+    "@astryxdesign/core": "0.1.6-canary.eba4f34",
+    "@astryxdesign/lab": "0.1.6-canary.eba4f34",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eba4f34",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/template.mjs

@@ -6,7 +6,6 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {createJiti} from 'jiti';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
 import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
@@ -22,54 +21,9 @@ import {Project} from '../lib/project.mjs';
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
-/**
- * Canonical basename suffixes for template-spec files, in precedence order.
- * A template spec exports a `createBlockTemplate`/`createPageTemplate` result
- * (a scaffoldable TEMPLATE), so `.template.*` is the descriptive family name.
- */
-const TEMPLATE_SUFFIXES = ['.template.ts', '.template.mjs', '.template.js'];
-
-/**
- * Legacy basename suffixes for template-spec files, in precedence order.
- * `.doc.*` was inherited from the component-doc convention before templates
- * had their own name; it is still accepted during the transition window.
- */
+/** Doc-file basename suffixes for integration templates, in precedence order. */
 const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
 
-/**
- * The union of canonical + legacy template-spec suffixes, canonical first so
- * `.template.*` wins over `.doc.*` when both stems exist. All template
- * discovery matches this union so a `Foo.template.ts` file is treated exactly
- * like a legacy `Foo.doc.mjs`.
- */
-const ALL_TEMPLATE_SUFFIXES = [...TEMPLATE_SUFFIXES, ...DOC_SUFFIXES];
-
-/**
- * The template-spec suffix present on `file`, or null if none matches.
- * Recognizes both the canonical `.template.*` and legacy `.doc.*` families.
- * @param {string} file
- * @returns {string | null}
- */
-function matchedTemplateSuffix(file) {
-  return ALL_TEMPLATE_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
-}
-
-/**
- * RegExp matching either template-spec suffix family at end of a basename.
- * Used where a per-file regex is convenient (e.g. block discovery walks).
- */
-const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
-
-let jitiInstance;
-/** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
-function getJiti() {
-  if (!jitiInstance) {
-    jitiInstance = createJiti(import.meta.url, {jsx: true});
-  }
-  return jitiInstance;
-}
-
-
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -133,29 +87,12 @@ export function stripTemplateAssetRefs(source) {
     source,
   );
 }
-/**
- * Load a template-spec module and return its metadata object. Supports both
- * families of suffix:
- *   - Legacy `.doc.*` core/external specs export `export const doc = {...}`.
- *   - Specs authored with `createPageTemplate`/`createBlockTemplate` export the
- *     stamped object as the default export.
- * Prefers the default export, falling back to the named `doc` export, so a
- * `Foo.template.ts` (default export) is read identically to a legacy
- * `Foo.doc.mjs` (`doc` export). `.ts` is loaded via jiti; `.mjs`/`.js` via a
- * native dynamic import. Returns null if the file does not exist.
- *
- * @param {string} docPath absolute path to the spec file
- * @returns {Promise<Record<string, unknown> | undefined | null>}
- */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
-  const docModule = docPath.endsWith('.ts')
-    ? await getJiti().import(docPath)
-    : await import(`file://${docPath}`);
-  return docModule.default ?? docModule.doc;
+  const docModule = await import(`file://${docPath}`);
+  return docModule.doc;
 }
 
-
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
@@ -185,20 +122,6 @@ function findDocFiles(dir, pattern) {
   return results;
 }
 
-/**
- * Resolve the template-spec file for a core page directory: the first existing
- * `template.<suffix>` in canonical-then-legacy precedence, or null.
- * @param {string} dirPath
- * @returns {string | null}
- */
-function findPageDocFile(dirPath) {
-  for (const suffix of ALL_TEMPLATE_SUFFIXES) {
-    const candidate = path.join(dirPath, `template${suffix}`);
-    if (fs.existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
 async function discoverPages() {
   if (!fs.existsSync(PAGES_DIR)) return [];
   const dirs = fs
@@ -208,9 +131,7 @@ async function discoverPages() {
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
-    const docPath =
-      findPageDocFile(dirPath) ?? path.join(dirPath, 'template.doc.mjs');
-    const doc = await loadDocModule(docPath);
+    const doc = await loadDocModule(path.join(dirPath, 'template.doc.mjs'));
     templates.push({
       type: 'page',
       dirName: dir.name,
@@ -220,18 +141,17 @@ async function discoverPages() {
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
-      docPath,
+      docPath: path.join(dirPath, 'template.doc.mjs'),
     });
   }
   return templates;
 }
 
 async function discoverBlocks() {
-  const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
+  const docFiles = findDocFiles(BLOCKS_DIR, /\.doc\.mjs$/);
   const blocks = [];
   for (const docPath of docFiles) {
-    const suffix = matchedTemplateSuffix(docPath);
-    const basename = path.basename(docPath, suffix);
+    const basename = path.basename(docPath, '.doc.mjs');
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
     const doc = await loadDocModule(docPath);
@@ -253,7 +173,6 @@ async function discoverBlocks() {
   return blocks;
 }
 
-
 /**
  * Discover blocks from external packages that declare `astryx.blocks` in
  * their package.json. Same shape as discoverBlocks() output.
@@ -266,10 +185,9 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 
   for (const ext of externals) {
     if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
-    const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
+    const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);
     for (const docPath of docFiles) {
-      const suffix = matchedTemplateSuffix(docPath);
-      const basename = path.basename(docPath, suffix);
+      const basename = path.basename(docPath, '.doc.mjs');
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
       const doc = await loadDocModule(docPath);
@@ -340,9 +258,8 @@ async function discoverAllWithErrors(cwd = process.cwd()) {
 export {discoverAllWithErrors};
 
 /**
- * Recursively collect integration template-spec files under `root`.
- * Returns absolute paths to files ending in one of ALL_TEMPLATE_SUFFIXES
- * (canonical `.template.*` or legacy `.doc.*`).
+ * Recursively collect integration template doc files under `root`.
+ * Returns absolute paths to files ending in one of DOC_SUFFIXES.
  *
  * @param {string} root
  * @returns {string[]}
@@ -355,7 +272,7 @@ function findIntegrationDocFiles(root) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+      } else if (DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
         results.push(full);
       }
     }
@@ -364,17 +281,24 @@ function findIntegrationDocFiles(root) {
   return results;
 }
 
+/**
+ * The doc-file suffix present on `file`, or null if none matches.
+ * @param {string} file
+ */
+function matchedDocSuffix(file) {
+  return DOC_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
+}
+
 /**
  * Discover templates contributed by configured integrations.
  *
  * For each integration with a resolved `templates` root, every
- * `<id>.template.{ts,mjs,js}` (or legacy `<id>.doc.{ts,mjs,js}`) file is a
- * template whose id is its path relative to the templates root with the
- * matched suffix stripped (kebab-case, may be nested). The doc's `type`
- * (page|block) decides scaffolding — there is no `/pages` vs `/blocks`
- * requirement. A same-stem sibling source file (`<id>.tsx`) is required; a doc
- * missing its source, or missing `type`, is an integration error and that
- * template is skipped (recorded in `errors`).
+ * `<id>.doc.{ts,mjs,js}` file is a template whose id is its path relative to
+ * the templates root with the `.doc.*` suffix stripped (kebab-case, may be
+ * nested). The doc's `type` (page|block) decides scaffolding — there is no
+ * `/pages` vs `/blocks` requirement. A same-stem sibling source file
+ * (`<id>.tsx`) is required; a doc missing its source, or missing `type`, is
+ * an integration error and that template is skipped (recorded in `errors`).
  *
  * @param {string} [cwd]
  * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
@@ -420,7 +344,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   if (!root || !fs.existsSync(root)) return {templates, errors};
 
   for (const docPath of findIntegrationDocFiles(root)) {
-    const suffix = matchedTemplateSuffix(docPath);
+    const suffix = matchedDocSuffix(docPath);
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)

package/templates/blocks/components/Avatar/AvatarGroup.tsx

@@ -7,26 +7,28 @@ import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
 import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
 
+const CDN = 'https://lookaside.facebook.com/assets/astryx';
+
 const USERS = [
   {
     name: 'Ami Pena',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png',
+    src: `${CDN}/DATA-Ami-Pena.png`,
   },
   {
     name: 'Drew Young',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png',
+    src: `${CDN}/DATA-Drew-Young.png`,
   },
   {
     name: 'Gabriela Fernandez',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png',
+    src: `${CDN}/DATA-Gabriela-Fernandez.png`,
   },
   {
     name: 'Jihoo Song',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png',
+    src: `${CDN}/DATA-Jihoo-Song.png`,
   },
   {
     name: 'Nam Tran',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png',
+    src: `${CDN}/DATA-Nam-Tran.png`,
   },
 ];
 

package/templates/blocks/components/Avatar/AvatarShowcase.tsx

@@ -5,27 +5,29 @@
 import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
+const CDN = 'https://lookaside.facebook.com/assets/astryx';
+
 export default function AvatarShowcase() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
+        src={`${CDN}/DATA-Ana-Thomas.png`}
         name="Ana Thomas"
         size="large"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png"
+        src={`${CDN}/DATA-Drew-Young.png`}
         name="Drew Young"
         size="large"
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png"
+        src={`${CDN}/DATA-Jihoo-Song.png`}
         name="Jihoo Song"
         size="large"
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png"
+        src={`${CDN}/DATA-Nam-Tran.png`}
         name="Nam Tran"
         size="large"
         status={<AvatarStatusDot variant="error" label="Online" />}

package/templates/blocks/components/Avatar/AvatarUserCard.tsx

@@ -6,22 +6,24 @@ import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
 
+const CDN = 'https://lookaside.facebook.com/assets/astryx';
+
 const USERS = [
   {
     name: 'Itai Jordaan',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png',
+    src: `${CDN}/DATA-Itai-Jordaan.png`,
     role: 'Engineering Lead',
     variant: 'success' as const,
   },
   {
     name: 'Margot Schroder',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png',
+    src: `${CDN}/DATA-Margot-Schroder.png`,
     role: 'Product Designer',
     variant: 'neutral' as const,
   },
   {
     name: 'Daniela Gimenez',
-    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png',
+    src: `${CDN}/DATA-Daniela-Gimenez.png`,
     role: 'Engineering Manager',
     variant: 'error' as const,
   },

package/templates/blocks/components/Avatar/AvatarWithImage.tsx

@@ -5,26 +5,24 @@
 import {Avatar} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
+const CDN = 'https://lookaside.facebook.com/assets/astryx';
+
 export default function AvatarWithImage() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
+      <Avatar src={`${CDN}/DATA-Ami-Pena.png`} name="Ami Pena" size="tiny" />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
-        name="Ami Pena"
-        size="tiny"
-      />
-      <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
+        src={`${CDN}/DATA-Ana-Thomas.png`}
         name="Ana Thomas"
         size="small"
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
+        src={`${CDN}/DATA-Daniela-Gimenez.png`}
         name="Daniela Gimenez"
         size="medium"
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png"
+        src={`${CDN}/DATA-Gabriela-Fernandez.png`}
         name="Gabriela Fernandez"
         size="large"
       />

package/templates/blocks/components/Avatar/AvatarWithStatus.tsx

@@ -5,23 +5,25 @@
 import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
+const CDN = 'https://lookaside.facebook.com/assets/astryx';
+
 export default function AvatarWithStatus() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png"
+        src={`${CDN}/DATA-Itai-Jordaan.png`}
         name="Itai Jordaan"
         size="large"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png"
+        src={`${CDN}/DATA-Margot-Schroder.png`}
         name="Margot Schroder"
         size="large"
         status={<AvatarStatusDot variant="neutral" label="Offline" />}
       />
       <Avatar
-        src="https://lookaside.facebook.com/assets/astryx/DATA-Pablo-Morales.png"
+        src={`${CDN}/DATA-Pablo-Morales.png`}
         name="Pablo Morales"
         size="large"
         status={<AvatarStatusDot variant="error" label="Busy" />}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputControlledInput.tsx

@@ -10,7 +10,7 @@ import {Text} from '@astryxdesign/core/Text';
 export default function ChatComposerInputControlledInput() {
   const [value, setValue] = useState('');
   return (
-    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         value={value}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputDisabled.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputDisabled() {
   return (
-    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
       <ChatComposer
         onSubmit={() => {}}
         isDisabled

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMentionTrigger.tsx

@@ -43,7 +43,7 @@ export default function ChatComposerInputMentionTrigger() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMultipleTriggers.tsx

@@ -54,7 +54,7 @@ export default function ChatComposerInputMultipleTriggers() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
       <Text type="supporting" color="secondary">
         Type @ for mentions (blue) or / for commands (yellow)
       </Text>

package/templates/blocks/components/ChatComposerInput/ChatComposerInputShowcase.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputShowcase() {
   return (
-    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputSlashCommands.tsx

@@ -40,7 +40,7 @@ export default function ChatComposerInputSlashCommands() {
   };
 
   return (
-    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
+    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/pages/theme-showcase/page.tsx

@@ -282,14 +282,14 @@ const DEFAULT_PRODUCTS: ProductSpec[] = [
 
 // Neutral product photos, served from the shared astryx asset CDN so the
 // scaffolded template renders real imagery without needing local public assets.
+const NEUTRAL_CDN = 'https://lookaside.facebook.com/assets/astryx';
 const DEFAULT_IMAGES: Record<string, string> = {
-  watch: 'https://lookaside.facebook.com/assets/astryx/Neutral-Watch.png',
-  headphones:
-    'https://lookaside.facebook.com/assets/astryx/Neutral-Headphones.png',
-  backpack: 'https://lookaside.facebook.com/assets/astryx/Neutral-Backpack.png',
-  wallet: 'https://lookaside.facebook.com/assets/astryx/Neutral-Wallet.png',
-  tumbler: 'https://lookaside.facebook.com/assets/astryx/Neutral-Tumbler.png',
-  throw_: 'https://lookaside.facebook.com/assets/astryx/Neutral-Blanket.png',
+  watch: `${NEUTRAL_CDN}/Neutral-Watch.png`,
+  headphones: `${NEUTRAL_CDN}/Neutral-Headphones.png`,
+  backpack: `${NEUTRAL_CDN}/Neutral-Backpack.png`,
+  wallet: `${NEUTRAL_CDN}/Neutral-Wallet.png`,
+  tumbler: `${NEUTRAL_CDN}/Neutral-Tumbler.png`,
+  throw_: `${NEUTRAL_CDN}/Neutral-Blanket.png`,
 };
 
 export interface ThemeShowcaseProps {

package/docs/integration-authoring.md

@@ -1,105 +0,0 @@
-# Authoring an Astryx Integration
-
-> **Status:** working notes. This should eventually move to the public wiki
-> alongside the rest of the integration-authoring guidance; it lives here for
-> now so it ships and is versioned with the CLI.
-
-An **Integration** is an npm package that contributes components, templates, and/or
-codemods to a consumer's design-system workflow. Consumers install the 3rd party
-package, add a line to their astryx.config file:
-
-```js
-import {createConfig} from '@astryxdesign/cli/config';
-
-export default createConfig({
-  integrations: ['@acme/astryx-widgets'],
-  ...
-});
-```
-
-Then the integration's components and templates will be surfaced alongside Astryx
-components in the Astryx CLI.
-
-```sh
-astryx component AcmeCarousel --props
-astryx component --list --package @acme/astryx-widgets
-```
-
-## The Integration File
-
-In order to register your package as an Astryx Integration, create an
-`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
-tells Astryx where to find your components, templates, codemods, etc.
-
-```js
-// astryx.integration.{ts,mjs,js}
-import {createIntegration} from '@astryxdesign/cli/integration';
-
-export default createIntegration({
-  components: './components',
-  templates: './templates',
-  codemods: './codemods',
-  issuesUrl: 'https://github.com/acme/widgets/issues',
-});
-```
-
-## Components
-
-Your components themselves may be exported from your library as you see fit (consumers
-will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
-file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
-
-```js
-// AcmeCarousel.doc.ts
-import {createComponentDoc} from '@astryxdesign/cli/doc';
-
-export default createComponentDoc({
-  name: 'AcmeCarousel',
-  description: '...',
-  ...
-});
-```
-
-## Templates
-
-Templates are typically not exported from the package directly, but instead accessed
-via the Astryx CLI. Consumers can look through your templates and materialize them
-into their apps.
-
-You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
-(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
-
-```js
-// AcmeLandingPage.template.ts
-import {createPageTemplate} from '@astryxdesign/cli/template';
-
-export default createPageTemplate({
-  ...
-});
-```
-
-Note that, since the CLI needs access to the template source code, you need to make sure
-that it is included in your published package. This will also allow us to render previews
-of templates in the future by bundling your template into a doc site build.
-
-Typically, this is done via the package.json `exports` key.
-
-```jsonc
-{
-  "exports": {
-    // ...
-    "./templates/*.tsx": "./templates/*.tsx",
-  },
-}
-```
-
-In order to verify that it's working, you can test importing the template component like this:
-
-```ts
-import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
-```
-
-Import **with the `.tsx` extension** — an extensionless specifier won't resolve
-under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
-above is what lets that import type-check without consumers enabling
-`allowImportingTsExtensions`.

package/src/api/integration-block-exports.test.mjs

@@ -1,240 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Proves the minimal `exports` recipe an integration package needs so a
- * bundler-resolution consumer can `import()` its block templates AND type-check
- * them under `moduleResolution: bundler`.
- *
- * Integration packages in this ecosystem ship TypeScript SOURCE — their block
- * templates are `.tsx` files with no compiled `.d.ts`. A later feature renders
- * showcase previews by a REAL dynamic `import()` of a block's `.tsx` source
- * (e.g. `import('@acme/widgets/templates/Gauge/GaugeShowcase.tsx')`) instead of
- * eval'ing source text. For that import to resolve, the integration's
- * `package.json#exports` map must GATE the deep path.
- *
- * These tests stand up a throwaway `@acme/widgets` fixture and drive the two
- * gates that matter with the repo's own toolchain:
- *   1. `tsc --noEmit` under `moduleResolution: bundler` (the consumer profile
- *      used by the Next.js example apps — NO `allowImportingTsExtensions`).
- *   2. `esbuild --bundle` (a real bundler resolving + loading the deep import).
- *
- * CANONICAL RECIPE (see integration-authoring.md):
- *   exports: { "./templates/*.tsx": "./templates/*.tsx" }
- *   import:  import('@acme/widgets/templates/<Name>/<Name>Showcase.tsx')   // WITH .tsx
- *
- * The negative controls lock in WHY the extension is required: a bare
- * `./templates/*` export with an extensionless import fails to type-check under
- * bundler resolution (TS cannot infer the `.tsx` extension for a deep
- * specifier), and an extensionless import fails to bundle.
- */
-
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import {createRequire} from 'node:module';
-import {execFileSync} from 'node:child_process';
-
-const require = createRequire(import.meta.url);
-
-/** Resolve the workspace tsc/esbuild binaries; null if unavailable. */
-function resolveBin(spec) {
-  try {
-    return require.resolve(spec);
-  } catch {
-    return null;
-  }
-}
-const TSC_BIN = resolveBin('typescript/bin/tsc');
-const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
-
-let tmpDir;
-
-/**
- * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
- * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
- * manifest, plus a caller-supplied `exports` map.
- * @param {Record<string, string> | undefined} exportsMap
- */
-function makeWidgets(exportsMap) {
-  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
-  const blockDir = path.join(pkgDir, 'templates', 'Gauge');
-  fs.mkdirSync(blockDir, {recursive: true});
-
-  const pkg = {name: '@acme/widgets', version: '2.0.0', type: 'module'};
-  if (exportsMap) pkg.exports = exportsMap;
-  fs.writeFileSync(
-    path.join(pkgDir, 'package.json'),
-    JSON.stringify(pkg, null, 2),
-  );
-  fs.writeFileSync(
-    path.join(pkgDir, 'astryx.integration.mjs'),
-    `export default { templates: './templates' };\n`,
-  );
-  // The template-spec doc (canonical `.template.*` family).
-  fs.writeFileSync(
-    path.join(blockDir, 'GaugeShowcase.template.ts'),
-    `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
-  );
-  // The same-stem `.tsx` SOURCE that a preview will dynamically import().
-  // Returns a plain value so the fixture type-checks without React types.
-  fs.writeFileSync(
-    path.join(blockDir, 'GaugeShowcase.tsx'),
-    `const GaugeShowcase = (): string => 'gauge-showcase';\n` +
-      `export default GaugeShowcase;\n`,
-  );
-  return pkgDir;
-}
-
-/** Write a consumer that dynamically imports the given specifier. */
-function writeConsumer(specifier) {
-  fs.writeFileSync(
-    path.join(tmpDir, 'consumer.ts'),
-    `const load = () => import('${specifier}');\nexport default load;\n`,
-  );
-}
-
-/**
- * The realistic consumer tsconfig: matches the repo's Next.js example apps
- * (`moduleResolution: bundler`, `noEmit`, and deliberately NO
- * `allowImportingTsExtensions`).
- */
-function writeTsconfig() {
-  fs.writeFileSync(
-    path.join(tmpDir, 'tsconfig.json'),
-    JSON.stringify(
-      {
-        compilerOptions: {
-          target: 'ES2022',
-          lib: ['ES2022', 'DOM', 'DOM.Iterable'],
-          module: 'ESNext',
-          moduleResolution: 'bundler',
-          jsx: 'react-jsx',
-          strict: true,
-          skipLibCheck: true,
-          esModuleInterop: true,
-          noEmit: true,
-          isolatedModules: true,
-        },
-        include: ['consumer.ts'],
-      },
-      null,
-      2,
-    ),
-  );
-}
-
-/** @returns {{ok: boolean, out: string}} */
-function runTsc() {
-  try {
-    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
-      cwd: tmpDir,
-      stdio: 'pipe',
-    });
-    return {ok: true, out: ''};
-  } catch (e) {
-    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
-  }
-}
-
-/** @returns {{ok: boolean, out: string}} */
-function runEsbuild() {
-  try {
-    // esbuild's bin is a native executable (not a node script), so invoke it
-    // directly rather than through process.execPath.
-    execFileSync(
-      ESBUILD_BIN,
-      [
-        'consumer.ts',
-        '--bundle',
-        '--format=esm',
-        '--loader:.tsx=tsx',
-        '--outfile=/dev/null',
-        '--log-level=error',
-      ],
-      {cwd: tmpDir, stdio: 'pipe'},
-    );
-    return {ok: true, out: ''};
-  } catch (e) {
-    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
-  }
-}
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-block-exports-'));
-  fs.writeFileSync(
-    path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', private: true, type: 'module'}),
-  );
-  writeTsconfig();
-});
-
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-const CANONICAL = 'import(@acme/widgets/templates/Gauge/GaugeShowcase.tsx)';
-const SPEC = '@acme/widgets/templates/Gauge/GaugeShowcase.tsx';
-
-describe('integration block-template exports recipe', () => {
-  it.runIf(TSC_BIN != null)(
-    `CANONICAL: exports {"./templates/*.tsx"} + ${CANONICAL} type-checks under bundler resolution`,
-    () => {
-      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
-      writeConsumer(SPEC);
-      const {ok, out} = runTsc();
-      expect(out).toBe('');
-      expect(ok).toBe(true);
-    },
-    30_000,
-  );
-
-  it.runIf(ESBUILD_BIN != null)(
-    `CANONICAL: the same import resolves + bundles with a real bundler`,
-    () => {
-      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
-      writeConsumer(SPEC);
-      const {ok, out} = runEsbuild();
-      expect(out).toBe('');
-      expect(ok).toBe(true);
-    },
-    30_000,
-  );
-
-  it.runIf(TSC_BIN != null)(
-    'NEGATIVE: an extensionless import does NOT type-check (TS cannot infer .tsx)',
-    () => {
-      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
-      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
-      const {ok, out} = runTsc();
-      expect(ok).toBe(false);
-      expect(out).toContain('TS2307');
-    },
-    30_000,
-  );
-
-  it.runIf(TSC_BIN != null)(
-    'NEGATIVE: a bare "./templates/*" export (no .tsx entry) does NOT type-check the .tsx import',
-    () => {
-      // Only a bare mapping — the extensionful subpath is not exported.
-      makeWidgets({'./templates/*': './templates/*'});
-      writeConsumer(SPEC);
-      const {ok, out} = runTsc();
-      expect(ok).toBe(false);
-      // Bare export forces the TS5097 opt-in requirement (allowImportingTsExtensions).
-      expect(out).toContain('TS5097');
-    },
-    30_000,
-  );
-
-  it.runIf(ESBUILD_BIN != null)(
-    'NEGATIVE: an extensionless import does NOT bundle against the .tsx-only export',
-    () => {
-      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
-      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
-      const {ok} = runEsbuild();
-      expect(ok).toBe(false);
-    },
-    30_000,
-  );
-});

package/src/api/template-suffix.test.mjs

@@ -1,246 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
- * to the legacy `.doc.{ts,mjs,js}` suffix.
- *
- * Template-spec files are named for what they are: a scaffoldable TEMPLATE that
- * exports `createBlockTemplate`/`createPageTemplate`. The `.doc.*` suffix was
- * inherited from the component-doc convention and is still accepted during the
- * transition. These tests stand up integration templates and external blocks in
- * both families and assert byte-for-byte-equivalent discovery + scaffolding.
- */
-
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {
-  template,
-  findShowcase,
-  findRelatedBlocks,
-} from './template.mjs';
-
-/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
-const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
-
-let tmpDir;
-let originalCwd;
-
-function makeConsumer() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-suffix-'));
-  fs.writeFileSync(
-    path.join(dir, 'package.json'),
-    JSON.stringify({name: 'consumer'}),
-  );
-  fs.writeFileSync(
-    path.join(dir, 'astryx.config.mjs'),
-    `export default { integrations: ['@acme/widgets'] };\n`,
-  );
-  return dir;
-}
-
-function installWidgets(consumerDir) {
-  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
-  fs.mkdirSync(path.join(pkgDir, 'templates'), {recursive: true});
-  fs.writeFileSync(
-    path.join(pkgDir, 'package.json'),
-    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
-  );
-  fs.writeFileSync(
-    path.join(pkgDir, 'astryx.integration.mjs'),
-    `export default { templates: './templates' };\n`,
-  );
-  return pkgDir;
-}
-
-/**
- * Write a template-spec file (default-export createPageTemplate/BlockTemplate)
- * plus its same-stem `.tsx` source under the templates root.
- * @param {string} pkgDir
- * @param {string} id
- * @param {{kind: 'page'|'block', suffix: string}} opts
- */
-function writeTemplate(pkgDir, id, {kind, suffix}) {
-  const docPath = path.join(pkgDir, 'templates', `${id}${suffix}`);
-  fs.mkdirSync(path.dirname(docPath), {recursive: true});
-  const create =
-    kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
-  fs.writeFileSync(
-    docPath,
-    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
-      `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
-  );
-  fs.writeFileSync(
-    path.join(pkgDir, 'templates', `${id}.tsx`),
-    `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
-  );
-}
-
-beforeEach(() => {
-  originalCwd = process.cwd();
-  tmpDir = makeConsumer();
-  process.chdir(tmpDir);
-});
-
-afterEach(() => {
-  process.chdir(originalCwd);
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('integration templates: .template.* discovered like legacy .doc.*', () => {
-  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
-    it(`discovers + lists a page template authored as ${suffix}`, async () => {
-      const pkgDir = installWidgets(tmpDir);
-      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
-
-      const result = await template(undefined, {list: true, cwd: tmpDir});
-      const entry = result.data.find(t => t.id === 'pricing');
-      expect(entry).toBeTruthy();
-      expect(entry.type).toBe('page');
-      expect(entry.package).toBe('@acme/widgets');
-      expect(entry.name).toBe('pricing name');
-      expect(entry.description).toBe('pricing desc');
-    });
-
-    it(`scaffolds a page template authored as ${suffix}`, async () => {
-      const pkgDir = installWidgets(tmpDir);
-      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
-
-      const result = await template('pricing', {
-        targetPath: './dest',
-        cwd: tmpDir,
-      });
-      expect(result.type).toBe('template.copy');
-      expect(result.data.fileName).toBe('page.tsx');
-      expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
-    });
-
-    it(`scaffolds a nested block template authored as ${suffix}`, async () => {
-      const pkgDir = installWidgets(tmpDir);
-      writeTemplate(pkgDir, 'marketing/hero', {kind: 'block', suffix});
-
-      const result = await template('marketing/hero', {
-        targetPath: './dest',
-        cwd: tmpDir,
-      });
-      expect(result.type).toBe('template.copy');
-      expect(result.data.fileName).toBe('hero.tsx');
-      expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
-    });
-  }
-
-  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
-    const pkgDir = installWidgets(tmpDir);
-    writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
-    writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
-
-    const result = await template(undefined, {list: true, cwd: tmpDir});
-    const gauge = result.data.find(t => t.id === 'gauge');
-    const chip = result.data.find(t => t.id === 'chip');
-
-    // Both discovered, both blocks, both from the same package, both ready.
-    for (const entry of [gauge, chip]) {
-      expect(entry).toBeTruthy();
-      expect(entry.type).toBe('block');
-      expect(entry.package).toBe('@acme/widgets');
-    }
-    // Field-by-field parity apart from the (intentionally different) id/name.
-    expect(gauge.type).toBe(chip.type);
-    expect(gauge.package).toBe(chip.package);
-  });
-});
-
-describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
-  /**
-   * Create a consumer whose @test/ext package contributes two showcase blocks,
-   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
-   */
-  function makeShowcaseFixture() {
-    // Symlink the real core package (needed by findCoreDir during discovery).
-    const realCoreDir = path.resolve(
-      import.meta.dirname,
-      '..',
-      '..',
-      '..',
-      'core',
-    );
-    const coreDir = path.join(tmpDir, 'packages', 'core');
-    fs.mkdirSync(path.dirname(coreDir), {recursive: true});
-    fs.symlinkSync(realCoreDir, coreDir);
-
-    const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
-    const blocksDir = path.join(extDir, 'blocks', 'components');
-
-    // Foo showcase — canonical .template.ts (default-export createBlockTemplate).
-    const fooDir = path.join(blocksDir, 'Foo');
-    fs.mkdirSync(fooDir, {recursive: true});
-    fs.writeFileSync(
-      path.join(fooDir, 'FooShowcase.template.ts'),
-      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
-        `export default createBlockTemplate({\n` +
-        `  name: 'Foo — Showcase',\n` +
-        `  description: 'Foo showcase.',\n` +
-        `  isShowcase: true,\n` +
-        `  aspectRatio: 16 / 9,\n` +
-        `  componentsUsed: ['Foo'],\n` +
-        `});\n`,
-    );
-    fs.writeFileSync(
-      path.join(fooDir, 'FooShowcase.tsx'),
-      "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
-    );
-
-    // Bar showcase — legacy .doc.mjs (export const doc).
-    const barDir = path.join(blocksDir, 'Bar');
-    fs.mkdirSync(barDir, {recursive: true});
-    fs.writeFileSync(
-      path.join(barDir, 'BarShowcase.doc.mjs'),
-      `export const doc = {\n` +
-        `  type: 'block',\n` +
-        `  name: 'Bar — Showcase',\n` +
-        `  description: 'Bar showcase.',\n` +
-        `  isReady: true,\n` +
-        `  isShowcase: true,\n` +
-        `  aspectRatio: 4 / 3,\n` +
-        `  componentsUsed: ['Bar', 'Chip'],\n` +
-        `};\n`,
-    );
-    fs.writeFileSync(
-      path.join(barDir, 'BarShowcase.tsx'),
-      "'use client';\nexport default function BarShowcase() { return <div>Bar</div>; }",
-    );
-
-    fs.writeFileSync(
-      path.join(extDir, 'package.json'),
-      JSON.stringify({
-        name: '@test/ext',
-        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
-      }),
-    );
-    fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
-  }
-
-  it('findShowcase resolves a .template.ts external block by directory name', async () => {
-    makeShowcaseFixture();
-    const result = await findShowcase('Foo', tmpDir);
-    expect(result).not.toBeNull();
-    expect(result.name).toBe('Foo — Showcase');
-    expect(result.filePath).toContain('FooShowcase.tsx');
-  });
-
-  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
-    makeShowcaseFixture();
-    const result = await findShowcase('Bar', tmpDir);
-    expect(result).not.toBeNull();
-    expect(result.name).toBe('Bar — Showcase');
-  });
-
-  it('findRelatedBlocks finds both suffix families', async () => {
-    makeShowcaseFixture();
-    const foo = await findRelatedBlocks('Foo', tmpDir);
-    expect(foo.map(b => b.dirName)).toContain('FooShowcase');
-    const chip = await findRelatedBlocks('Chip', tmpDir);
-    expect(chip.map(b => b.dirName)).toContain('BarShowcase');
-  });
-});