@astryxdesign/cli 0.1.1 → 0.1.2-canary.043f3fd

package/src/api/template.mjs

@@ -6,11 +6,38 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {loadModuleWithSchema} from '../lib/module-loader.mjs';
+import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
-import {assertWithin, isFilePathArg, PathSafetyError} from '../utils/path-safety.mjs';
+import {
+  assertWithin,
+  isFilePathArg,
+  PathSafetyError,
+} from '../utils/path-safety.mjs';
 import {AstryxError} from './error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {loadConfig} from '../lib/config.mjs';
+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. */
+const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
+
+/**
+ * Load an integration template doc module and validate it against the template
+ * envelope at the load boundary. Default export only — `.ts` via jiti,
+ * `.mjs`/`.js` via dynamic import. Throws (caught by discovery) if the default
+ * export is missing or fails {@link TemplateEnvelopeSchema}. NOTE: the built-in
+ * core templates use `export const doc = {...}` and are loaded by a different
+ * function ({@link loadDocModule}) — this path is for INTEGRATION templates.
+ *
+ * @param {string} file
+ * @param {string} [label]
+ */
+async function loadIntegrationDoc(file, label) {
+  return loadModuleWithSchema(file, TemplateEnvelopeSchema, {label});
+}
 
 const TEMPLATES_DIR = path.join(CLI_ROOT, 'templates');
 const PAGES_DIR = path.join(TEMPLATES_DIR, 'pages');
@@ -23,7 +50,7 @@ const BLOCKS_DIR = path.join(TEMPLATES_DIR, 'blocks');
  * or not. Mirrors apps/docsite/public/template-assets/placeholder.svg.
  */
 const PLACEHOLDER_IMAGE =
-  "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20400%20300%22%20preserveAspectRatio%3D%22xMidYMid%20slice%22%3E%3Crect%20width%3D%22400%22%20height%3D%22300%22%20fill%3D%22%23f5f6f8%22%2F%3E%3Cg%20transform%3D%22translate%28200%20150%29%22%20fill%3D%22none%22%20stroke%3D%22%23c2cad6%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Crect%20x%3D%22-44%22%20y%3D%22-44%22%20width%3D%2288%22%20height%3D%2288%22%20rx%3D%2216%22%2F%3E%3Ccircle%20cx%3D%2218%22%20cy%3D%22-18%22%20r%3D%222.5%22%20fill%3D%22%23c2cad6%22%20stroke%3D%22none%22%2F%3E%3Cpath%20d%3D%22M-34%2030%20L-8%200%20L10%2018%20L20%208%20L34%2024%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E";
+  'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20400%20300%22%20preserveAspectRatio%3D%22xMidYMid%20slice%22%3E%3Crect%20width%3D%22400%22%20height%3D%22300%22%20fill%3D%22%23f5f6f8%22%2F%3E%3Cg%20transform%3D%22translate%28200%20150%29%22%20fill%3D%22none%22%20stroke%3D%22%23c2cad6%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Crect%20x%3D%22-44%22%20y%3D%22-44%22%20width%3D%2288%22%20height%3D%2288%22%20rx%3D%2216%22%2F%3E%3Ccircle%20cx%3D%2218%22%20cy%3D%22-18%22%20r%3D%222.5%22%20fill%3D%22%23c2cad6%22%20stroke%3D%22none%22%2F%3E%3Cpath%20d%3D%22M-34%2030%20L-8%200%20L10%2018%20L20%208%20L34%2024%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E';
 
 /**
  * Demo-image sources to strip from scaffolded projects — Meta's lookaside CDN
@@ -60,9 +87,12 @@ export {discoverAll as discoverTemplates};
 export function listTemplates() {
   const all = [];
   if (fs.existsSync(PAGES_DIR)) {
-    all.push(...fs.readdirSync(PAGES_DIR, {withFileTypes: true})
-      .filter(e => e.isDirectory())
-      .map(e => e.name));
+    all.push(
+      ...fs
+        .readdirSync(PAGES_DIR, {withFileTypes: true})
+        .filter(e => e.isDirectory())
+        .map(e => e.name),
+    );
   }
   return all.sort();
 }
@@ -83,7 +113,8 @@ function findDocFiles(dir, pattern) {
 
 async function discoverPages() {
   if (!fs.existsSync(PAGES_DIR)) return [];
-  const dirs = fs.readdirSync(PAGES_DIR, {withFileTypes: true})
+  const dirs = fs
+    .readdirSync(PAGES_DIR, {withFileTypes: true})
     .filter(e => e.isDirectory());
 
   const templates = [];
@@ -132,8 +163,8 @@ async function discoverBlocks() {
 }
 
 /**
- * Discover blocks from external packages that declare `xds.blocks`.
- * Same shape as discoverBlocks() output.
+ * Discover blocks from external packages that declare `astryx.blocks` in
+ * their package.json. Same shape as discoverBlocks() output.
  *
  * @param {string} [cwd]
  */
@@ -182,20 +213,190 @@ async function discoverAllBlocks(cwd = process.cwd()) {
   return [...core, ...external];
 }
 
-async function discoverAll() {
-  const [pages, blocks] = await Promise.all([
+async function discoverAll(cwd = process.cwd()) {
+  const [pages, blocks, integration] = await Promise.all([
     discoverPages(),
-    discoverAllBlocks(),
+    discoverAllBlocks(cwd),
+    discoverIntegrationTemplates(cwd),
   ]);
-  return [...pages, ...blocks].sort((a, b) => a.name.localeCompare(b.name));
+  return [...pages, ...blocks, ...integration.templates].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
+
+/**
+ * Like {@link discoverAll} but also returns integration-template discovery
+ * errors (missing same-stem source, missing `type`, load failure). Use this
+ * when the caller wants to warn about malformed integration templates.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ */
+async function discoverAllWithErrors(cwd = process.cwd()) {
+  const [pages, blocks, integration] = await Promise.all([
+    discoverPages(),
+    discoverAllBlocks(cwd),
+    discoverIntegrationTemplates(cwd),
+  ]);
+  const templates = [...pages, ...blocks, ...integration.templates].sort(
+    (a, b) => a.name.localeCompare(b.name),
+  );
+  return {templates, errors: integration.errors};
+}
+
+export {discoverAllWithErrors};
+
+/**
+ * Recursively collect integration template doc files under `root`.
+ * Returns absolute paths to files ending in one of DOC_SUFFIXES.
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+function findIntegrationDocFiles(root) {
+  const results = [];
+  if (!fs.existsSync(root)) return results;
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+        results.push(full);
+      }
+    }
+  };
+  walk(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`).
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ */
+async function discoverIntegrationTemplates(cwd = process.cwd()) {
+  const templates = [];
+  const errors = [];
+
+  let loadedIntegrations;
+  try {
+    const project = await Project.load(cwd);
+    loadedIntegrations = project.loadedIntegrations;
+  } catch {
+    // Config load failures are surfaced elsewhere (discover/doctor); here we
+    // simply contribute no integration templates.
+    return {templates, errors};
+  }
+
+  for (const integration of loadedIntegrations) {
+    const result = await discoverIntegrationTemplatesForOne(integration);
+    templates.push(...result.templates);
+    errors.push(...result.errors);
+  }
+
+  return {templates, errors};
+}
+
+/**
+ * Discover the templates contributed by a SINGLE integration. Same per-template
+ * rules as {@link discoverIntegrationTemplates} (same-stem source required,
+ * page|block type required); broken templates are recorded in `errors` rather
+ * than thrown. Exposed for `validate-integration`.
+ *
+ * @param {{name?: string, __spec?: string, templates?: string}} integration
+ * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ */
+export async function discoverIntegrationTemplatesForOne(integration) {
+  const templates = [];
+  const errors = [];
+
+  const root = integration?.templates;
+  const pkgLabel = integration?.name ?? integration?.__spec ?? 'integration';
+  if (!root || !fs.existsSync(root)) return {templates, errors};
+
+  for (const docPath of findIntegrationDocFiles(root)) {
+    const suffix = matchedDocSuffix(docPath);
+    const id = path
+      .relative(root, docPath)
+      .slice(0, -suffix.length)
+      .split(path.sep)
+      .join('/');
+
+    const sourcePath = docPath.slice(0, -suffix.length) + '.tsx';
+    if (!fs.existsSync(sourcePath)) {
+      errors.push({
+        package: pkgLabel,
+        template: id,
+        message: `Template "${id}" is missing its same-stem source file ${path.basename(sourcePath)}.`,
+      });
+      continue;
+    }
+
+    let doc;
+    try {
+      doc = await loadIntegrationDoc(docPath, `Template "${id}"`);
+    } catch (err) {
+      errors.push({
+        package: pkgLabel,
+        template: id,
+        message: `Template "${id}" failed to load: ${err.message}`,
+      });
+      continue;
+    }
+
+    // loadIntegrationDoc validates against the envelope (incl. a 'page'|'block'
+    // type) at the load boundary, so a valid doc always has a type. This guard
+    // stays as defense-in-depth.
+    const type = doc?.type;
+    if (type !== 'page' && type !== 'block') {
+      errors.push({
+        package: pkgLabel,
+        template: id,
+        message: `Template "${id}" is missing a "type" of "page" or "block". Author it with createPageTemplate/createBlockTemplate.`,
+      });
+      continue;
+    }
+
+    templates.push({
+      type,
+      dirName: id,
+      name: doc?.name || id,
+      description: doc?.description || '',
+      category: doc?.category || '',
+      isReady: true,
+      scaffold: false,
+      componentsUsed: doc?.componentsUsed ?? [],
+      filePath: sourcePath,
+      docPath,
+      package: pkgLabel,
+    });
+  }
+
+  return {templates, errors};
 }
 
 export async function findRelatedBlocks(componentName, cwd) {
   const blocks = await discoverAllBlocks(cwd);
   return blocks.filter(b =>
-    b.componentsUsed.some(c =>
-      c.toLowerCase() === componentName.toLowerCase(),
-    ),
+    b.componentsUsed.some(c => c.toLowerCase() === componentName.toLowerCase()),
   );
 }
 
@@ -218,7 +419,7 @@ export async function findShowcase(componentName, cwd, options) {
     return true;
   });
 
-  const toResult = (b) => ({
+  const toResult = b => ({
     name: b.name,
     aspectRatio: b.aspectRatio,
     filePath: b.filePath,
@@ -242,8 +443,14 @@ export async function findShowcase(componentName, cwd, options) {
 }
 
 const UBIQUITOUS = new Set([
-  'Text', 'Heading', 'Button', 'HStack', 'VStack', 'Link',
-  'StackItem', 'Icon',
+  'Text',
+  'Heading',
+  'Button',
+  'HStack',
+  'VStack',
+  'Link',
+  'StackItem',
+  'Icon',
 ]);
 
 export function extractComponents(pagePath) {
@@ -259,22 +466,115 @@ export function extractComponents(pagePath) {
   while ((m = tagRegex.exec(src)) !== null) {
     matches.push(m[2]);
   }
-  return [...new Set(
-    matches
-      .filter(n => !['Theme', 'ThemeProvider'].includes(n))
-      .filter(n => !UBIQUITOUS.has(n))
-      .map(n => n.replace(/(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/, ''))
-      .filter(Boolean),
-  )].sort();
+  return [
+    ...new Set(
+      matches
+        .filter(n => !['Theme', 'ThemeProvider'].includes(n))
+        .filter(n => !UBIQUITOUS.has(n))
+        .map(n =>
+          n.replace(
+            /(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
+            '',
+          ),
+        )
+        .filter(Boolean),
+    ),
+  ].sort();
 }
 
 const STRUCTURAL = new Set([
-  'AppShell', 'Layout', 'LayoutHeader', 'LayoutContent', 'LayoutPanel',
-  'LayoutFooter', 'Card', 'Section', 'Grid', 'GridSpan', 'List',
-  'Table', 'TabList', 'Toolbar', 'SideNav', 'TopNav', 'Dialog',
-  'FormLayout', 'Center',
+  'AppShell',
+  'Layout',
+  'LayoutHeader',
+  'LayoutContent',
+  'LayoutPanel',
+  'LayoutFooter',
+  'Card',
+  'Section',
+  'Grid',
+  'GridSpan',
+  'List',
+  'Table',
+  'TabList',
+  'Toolbar',
+  'SideNav',
+  'TopNav',
+  'Dialog',
+  'FormLayout',
+  'Center',
 ]);
 
+const SPATIAL_PROPS = [
+  'padding',
+  'contentPadding',
+  'gap',
+  'rowGap',
+  'columnGap',
+  'columns',
+  'minChildWidth',
+  'hasDivider',
+  'defaultHasDividers',
+  'variant',
+  'density',
+  'role',
+  'height',
+  'width',
+  'maxWidth',
+];
+
+/**
+ * Copy allowlisted layout props verbatim from a JSX opening-tag fragment.
+ * Uses quote/brace matching so object literals and spaced strings stay intact.
+ *
+ * @param {string} tagText
+ * @returns {string[]}
+ */
+function extractSpatialAttrs(tagText) {
+  const attrs = [];
+  for (const name of SPATIAL_PROPS) {
+    const eqMatch = tagText.match(new RegExp(`\\b${name}\\s*=\\s*`));
+    if (eqMatch) {
+      const start = eqMatch.index;
+      let i = eqMatch.index + eqMatch[0].length;
+      const rest = tagText.slice(i);
+
+      if (rest[0] === '"' || rest[0] === "'") {
+        const q = rest[0];
+        i += 1;
+        while (i < tagText.length && tagText[i] !== q) {
+          if (tagText[i] === '\\') i += 1;
+          i += 1;
+        }
+        if (i < tagText.length) i += 1;
+      } else if (rest[0] === '{') {
+        let depth = 0;
+        while (i < tagText.length) {
+          if (tagText[i] === '{') depth += 1;
+          else if (tagText[i] === '}') {
+            depth -= 1;
+            if (depth === 0) {
+              i += 1;
+              break;
+            }
+          }
+          i += 1;
+        }
+      } else {
+        const bare = rest.match(/^[^\s/>]+/);
+        i += bare ? bare[0].length : 0;
+      }
+
+      attrs.push(tagText.slice(start, i).trim());
+      continue;
+    }
+
+    if (new RegExp(`\\b${name}(?=[\\s/>])`).test(tagText)) {
+      attrs.push(name);
+    }
+  }
+  return attrs;
+}
+
 function extractSkeleton(source) {
   const lines = source.split('\n');
   const out = [];
@@ -287,11 +587,18 @@ function extractSkeleton(source) {
   for (let i = 0; i < lines.length; i++) {
     const t = lines[i].trim();
 
-    if (t.match(/^export\s+default\s+function/)) { inDefaultExport = true; continue; }
-    if (inDefaultExport && t.match(/^return\s*\(/)) { capturing = true; continue; }
+    if (t.match(/^export\s+default\s+function/)) {
+      inDefaultExport = true;
+      continue;
+    }
+    if (inDefaultExport && t.match(/^return\s*\(/)) {
+      capturing = true;
+      continue;
+    }
     if (!capturing) continue;
     if (out.length >= MAX_LINES) {
-      if (!out[out.length - 1]?.includes('...')) out.push('  '.repeat(depth) + '...');
+      if (!out[out.length - 1]?.includes('...'))
+        out.push('  '.repeat(depth) + '...');
       continue;
     }
 
@@ -309,20 +616,13 @@ function extractSkeleton(source) {
         if (lines[j].includes('>')) break;
       }
 
-      const props = [];
-      const propRegex = /\b(padding|contentPadding|gap|rowGap|columnGap|columns|minChildWidth|hasDivider|defaultHasDividers|variant|density|role|height|width|maxWidth)\s*[=]\s*\{?\s*['"]?([^}'"\s,/>]+)/g;
-      let m;
-      while ((m = propRegex.exec(tagText)) !== null) {
-        const val = m[2];
-        if (val === 'true') props.push(m[1]);
-        else if (/^\d+$/.test(val)) props.push(`${m[1]}={${val}}`);
-        else props.push(`${m[1]}="${val}"`);
-      }
-
+      const props = extractSpatialAttrs(tagText);
       const hasSpatialProps = props.length > 0;
       const propStr = hasSpatialProps ? ' ' + props.join(' ') : '';
       const isVStack = comp === 'VStack' || comp === 'HStack';
-      const isSelfClosing = tagText.match(new RegExp('<' + tagName + '[^>]*/>', 's'));
+      const isSelfClosing = tagText.match(
+        new RegExp('<' + tagName + '[^>]*/>', 's'),
+      );
 
       if (isVStack && !hasSpatialProps) continue;
 
@@ -349,13 +649,18 @@ function extractSkeleton(source) {
       continue;
     }
 
-    const slotMatch = t.match(/^(header|content|footer|start|end|sideNav|topNav)\s*=\s*\{/);
+    const slotMatch = t.match(
+      /^(header|content|footer|start|end|sideNav|topNav)\s*=\s*\{/,
+    );
     if (slotMatch) {
       out.push('  '.repeat(depth) + `/* ${slotMatch[1]}: */`);
       continue;
     }
 
-    if (t.startsWith('<div') && (t.includes('padding') || t.includes('maxWidth') || t.includes('gap:'))) {
+    if (
+      t.startsWith('<div') &&
+      (t.includes('padding') || t.includes('maxWidth') || t.includes('gap:'))
+    ) {
       const styleProps = [];
       const divText = lines.slice(i, Math.min(i + 5, lines.length)).join(' ');
       const pp = divText.match(/padding[^:]*:\s*['"]?([^'"},)]+)/);
@@ -377,67 +682,6 @@ function extractSkeleton(source) {
   return out.filter(l => l.trim()).join('\n');
 }
 
-/**
- * Fetch a template by ID using the `template.get` hook in astryx.config.mjs.
- * @param {string} id
- * @param {object} [options]
- * @param {string} [options.cwd]
- * @returns {Promise<{type: 'template.get', data: {id: string, source: string}}>}
- */
-export async function getTemplateById(id, options = {}) {
-  const {cwd = process.cwd()} = options;
-  const config = await loadConfig(cwd);
-
-  const getter = config.template?.get;
-  if (typeof getter !== 'function') {
-    throw new AstryxError(
-      'Template fetching by ID is not configured.\n' +
-        'Add a template.get function to astryx.config.mjs:\n\n' +
-        '  export default {\n' +
-        '    template: {\n' +
-        "      get: async (id) => { /* return template source string */ },\n" +
-        '    },\n' +
-        '  };',
-      undefined,
-      ERROR_CODES.ERR_TEMPLATE_CONFIG,
-    );
-  }
-
-  let source;
-  try {
-    source = await getter(id);
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new AstryxError(`template.get("${id}") threw an error: ${detail}`, undefined, ERROR_CODES.ERR_TEMPLATE_GET);
-  }
-
-  if (source == null) {
-    throw new AstryxError(
-      `template.get("${id}") returned ${source} — no template found for that ID`,
-      undefined,
-      ERROR_CODES.ERR_TEMPLATE_GET,
-    );
-  }
-
-  if (typeof source !== 'string') {
-    throw new AstryxError(
-      `template.get("${id}") must return a string, got ${typeof source}`,
-      undefined,
-      ERROR_CODES.ERR_TEMPLATE_GET,
-    );
-  }
-
-  if (source.trim() === '') {
-    throw new AstryxError(
-      `template.get("${id}") returned an empty string`,
-      undefined,
-      ERROR_CODES.ERR_TEMPLATE_GET,
-    );
-  }
-
-  return {type: 'template.get', data: {id, source}};
-}
-
 /**
  * @param {string} [name]
  * @param {object} [options]
@@ -445,38 +689,77 @@ export async function getTemplateById(id, options = {}) {
  * @param {boolean} [options.list]
  * @param {boolean} [options.skeleton]
  * @param {boolean} [options.show]
- * @param {'page'|'block'} [options.type] - Filter list views by template kind.
+ * @param {'page'|'block'} [options.type] - Filter list views / narrow lookups by template kind.
+ * @param {string} [options.package] - Narrow lookups to a specific package (id-only matches across packages are ambiguous).
  * @param {string} [options.cwd]
  * @returns {Promise<{type: string, data: unknown}>}
  */
 export async function template(name, options = {}) {
-  const {list = false, skeleton = false, show = false, targetPath, type, cwd = process.cwd()} = options;
-  const templates = await discoverAll();
+  const {
+    list = false,
+    skeleton = false,
+    show = false,
+    targetPath,
+    type,
+    package: packageFilter,
+    cwd = process.cwd(),
+  } = options;
+  const templates = await discoverAll(cwd);
+
+  /**
+   * Identity for a template in package-scoped views. Core (built-in)
+   * templates have no `package` field; report them under @astryxdesign/core.
+   * @param {{package?: string}} t
+   */
+  const pkgOf = t => t.package ?? CORE_PACKAGE;
 
   if (list || (!name && !skeleton)) {
     let filtered = templates;
-    if (type) filtered = templates.filter(t => t.type === type);
+    if (type) filtered = filtered.filter(t => t.type === type);
+    if (packageFilter) filtered = filtered.filter(t => pkgOf(t) === packageFilter);
     return {
       type: 'template.list',
       data: filtered.map(t => ({
-        name: t.dirName,
+        id: t.dirName,
+        name: t.name,
+        // `displayName` retained for back-compat with existing consumers.
         displayName: t.name,
         description: t.description,
+        type: t.type,
+        package: pkgOf(t),
+        category: t.category || undefined,
+        componentsUsed: t.componentsUsed ?? undefined,
         isReady: t.isReady,
         scaffold: t.scaffold ?? false,
-        type: t.type,
       })),
     };
   }
 
-  const match = templates.find(t => t.dirName === name);
-  if (name && !match) {
+  // Resolve `name` to a single template. The same id can appear across types
+  // and/or packages (e.g. a core "hero" page and an integration "hero"
+  // block); narrow with --type / --package.
+  let candidates = templates.filter(t => t.dirName === name);
+  if (type) candidates = candidates.filter(t => t.type === type);
+  if (packageFilter) candidates = candidates.filter(t => pkgOf(t) === packageFilter);
+
+  if (name && candidates.length === 0) {
     throw new AstryxError(
       `Unknown template "${name}"`,
       templates.map(t => ({name: t.dirName, reason: `${t.type} template`})),
       ERROR_CODES.ERR_UNKNOWN_TEMPLATE,
     );
   }
+  if (name && candidates.length > 1) {
+    throw new AstryxError(
+      `Template "${name}" is ambiguous — narrow it with --type and/or --package.`,
+      candidates.map(t => ({
+        name: t.dirName,
+        reason: `${t.type} template in ${pkgOf(t)}`,
+      })),
+      ERROR_CODES.ERR_AMBIGUOUS_TEMPLATE,
+    );
+  }
+  const match = candidates[0];
 
   if (skeleton) {
     if (!match) {
@@ -487,7 +770,11 @@ export async function template(name, options = {}) {
       );
     }
     if (!fs.existsSync(match.filePath)) {
-      throw new AstryxError(`No source file found for template "${name}"`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+      throw new AstryxError(
+        `No source file found for template "${name}"`,
+        undefined,
+        ERROR_CODES.ERR_NO_SOURCE,
+      );
     }
     const src = fs.readFileSync(match.filePath, 'utf-8');
     return {
@@ -502,7 +789,11 @@ export async function template(name, options = {}) {
   }
 
   if (!fs.existsSync(match.filePath)) {
-    throw new AstryxError(`No source file found for template "${name}"`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+    throw new AstryxError(
+      `No source file found for template "${name}"`,
+      undefined,
+      ERROR_CODES.ERR_NO_SOURCE,
+    );
   }
 
   if (show || !targetPath) {
@@ -529,7 +820,11 @@ export async function template(name, options = {}) {
     });
   } catch (err) {
     if (err instanceof PathSafetyError) {
-      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      throw new AstryxError(
+        err.message,
+        undefined,
+        ERROR_CODES.ERR_PATH_TRAVERSAL,
+      );
     }
     throw err;
   }
@@ -546,9 +841,8 @@ export async function template(name, options = {}) {
     outputFilePath = resolvedTarget;
   } else {
     outputDir = resolvedTarget;
-    outputFileName = match.type === 'block'
-      ? path.basename(match.filePath)
-      : 'page.tsx';
+    outputFileName =
+      match.type === 'block' ? path.basename(match.filePath) : 'page.tsx';
     outputFilePath = path.join(outputDir, outputFileName);
   }
 
@@ -563,6 +857,11 @@ export async function template(name, options = {}) {
   const relOutput = path.relative(cwd, outputDir) || '.';
   return {
     type: 'template.copy',
-    data: {template: name, outputDir: relOutput, fileName: outputFileName, filesCopied: 1},
+    data: {
+      template: name,
+      outputDir: relOutput,
+      fileName: outputFileName,
+      filesCopied: 1,
+    },
   };
 }