@astryxdesign/cli 0.1.5 → 0.1.6-canary.02f2602

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

@@ -0,0 +1,246 @@
+// 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');
+  });
+});

package/src/api/template.mjs

@@ -6,8 +6,9 @@
 
 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 {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
 import {
   assertWithin,
@@ -21,9 +22,54 @@ import {Project} from '../lib/project.mjs';
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
-/** Doc-file basename suffixes for integration templates, in precedence order. */
+/**
+ * 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.
+ */
 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,
@@ -87,12 +133,29 @@ 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 = await import(`file://${docPath}`);
-  return docModule.doc;
+  const docModule = docPath.endsWith('.ts')
+    ? await getJiti().import(docPath)
+    : await import(`file://${docPath}`);
+  return docModule.default ?? docModule.doc;
 }
 
+
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
@@ -122,6 +185,20 @@ 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
@@ -131,7 +208,9 @@ async function discoverPages() {
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
-    const doc = await loadDocModule(path.join(dirPath, 'template.doc.mjs'));
+    const docPath =
+      findPageDocFile(dirPath) ?? path.join(dirPath, 'template.doc.mjs');
+    const doc = await loadDocModule(docPath);
     templates.push({
       type: 'page',
       dirName: dir.name,
@@ -141,17 +220,18 @@ async function discoverPages() {
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
-      docPath: path.join(dirPath, 'template.doc.mjs'),
+      docPath,
     });
   }
   return templates;
 }
 
 async function discoverBlocks() {
-  const docFiles = findDocFiles(BLOCKS_DIR, /\.doc\.mjs$/);
+  const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
   const blocks = [];
   for (const docPath of docFiles) {
-    const basename = path.basename(docPath, '.doc.mjs');
+    const suffix = matchedTemplateSuffix(docPath);
+    const basename = path.basename(docPath, suffix);
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
     const doc = await loadDocModule(docPath);
@@ -173,6 +253,7 @@ async function discoverBlocks() {
   return blocks;
 }
 
+
 /**
  * Discover blocks from external packages that declare `astryx.blocks` in
  * their package.json. Same shape as discoverBlocks() output.
@@ -185,9 +266,10 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 
   for (const ext of externals) {
     if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
-    const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);
+    const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
     for (const docPath of docFiles) {
-      const basename = path.basename(docPath, '.doc.mjs');
+      const suffix = matchedTemplateSuffix(docPath);
+      const basename = path.basename(docPath, suffix);
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
       const doc = await loadDocModule(docPath);
@@ -258,8 +340,9 @@ async function discoverAllWithErrors(cwd = process.cwd()) {
 export {discoverAllWithErrors};
 
 /**
- * Recursively collect integration template doc files under `root`.
- * Returns absolute paths to files ending in one of DOC_SUFFIXES.
+ * 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.*`).
  *
  * @param {string} root
  * @returns {string[]}
@@ -272,7 +355,7 @@ function findIntegrationDocFiles(root) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+      } else if (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
         results.push(full);
       }
     }
@@ -281,24 +364,17 @@ 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>.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`).
+ * `<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`).
  *
  * @param {string} [cwd]
  * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
@@ -344,7 +420,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   if (!root || !fs.existsSync(root)) return {templates, errors};
 
   for (const docPath of findIntegrationDocFiles(root)) {
-    const suffix = matchedDocSuffix(docPath);
+    const suffix = matchedTemplateSuffix(docPath);
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)

package/src/api/validate-integration.mjs

@@ -67,11 +67,6 @@ function error(code, message) {
   return {code, severity: 'error', message};
 }
 
-/** @param {string} code @param {string} message @returns {Issue} */
-function warning(code, message) {
-  return {code, severity: 'warning', message};
-}
-
 /**
  * Verify each declared contribution root exists on disk. A declared-but-missing
  * root is a `missing_root` error.
@@ -365,6 +360,3 @@ export function summarizeIssues(issues) {
   }
   return {errors, warnings};
 }
-
-// Re-export issue constructors for callers/tests that want them.
-export {error as integrationError, warning as integrationWarning};

package/src/config.mjs

@@ -1,18 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * Type-preserving helper for the Astryx config file.
- *
- * This is an intentionally tiny runtime identity function: it returns its
- * argument unchanged. Its value is the exported TypeScript surface from
- * `@astryxdesign/cli/config`, so config files get editor/type feedback without
- * coupling to CLI internals. Validation is NOT performed here — it happens at
- * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).
- *
- * @template {import('./types/config').AstryxConfig} T
- * @param {T} config
- * @returns {T}
+ * Re-export of the config-authoring helper, which now lives in
+ * `@astryxdesign/core/config` so an app's config file gets type feedback
+ * without depending on the CLI. Kept here so existing
+ * `@astryxdesign/cli/config` imports continue to work unchanged.
  */
-export function createConfig(config) {
-  return config;
-}
+export {createConfig} from '@astryxdesign/core/config';

package/src/doc.mjs

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc-authoring API (public `@astryxdesign/cli/doc`).
+ *
+ * The `createComponentDoc`/`createFunctionDoc`/`createDoc` authoring helpers now
+ * live in `@astryxdesign/core/authoring` and are re-exported here so existing
+ * `@astryxdesign/cli/doc` imports keep working. The Zod load-boundary schemas
+ * live in `./schemas/doc-schema.mjs` (core-free) and are re-exported here for
+ * back-compat; internal hot-path code imports them from the schema module
+ * directly so it never depends on core's built `dist/`.
+ */
+
+export {
+  createComponentDoc,
+  createFunctionDoc,
+  createDoc,
+} from '@astryxdesign/core/authoring';
+
+export {
+  ComponentDocKindSchema,
+  FunctionDocKindSchema,
+  GenericDocKindSchema,
+  StampedDocSchema,
+  LegacyDocSchema,
+  ComponentDocSchema,
+} from './schemas/doc-schema.mjs';