An open source design system that's fully customizable and agent ready
TypeScript
refactor(cli): split template into api/template leaf shape (#4487)
Joey6aa0b6d8e379
diff --git a/.changeset/cli-template-leaves.md b/.changeset/cli-template-leaves.mdnew file mode 100644index 0000000000..dcb023116d--- /dev/null+++ b/.changeset/cli-template-leaves.md@@ -0,0 +1,6 @@+---+'@astryxdesign/cli': patch+---++[refactor] CLI: template reorganized into api/template leaf shape (shared helpers preserved on the barrel). Pure reorg — `--json` and human output stay byte-identical: shared discovery/IO moved to `api/template/_adapter.mjs`, the command modes split into `list`/`show`/`skeleton`/`copy` leaves, and `template.mjs` becomes a dispatcher + barrel that re-exports every previously-exported symbol (template, discoverTemplates, discoverAll, discoverAllWithErrors, discoverIntegrationTemplatesForOne, findShowcase, findRelatedBlocks, stripTemplateAssetRefs, listTemplates, extractComponents, and the DiscoveredTemplate/TemplateDiscoveryError types) so component/layout/search/init/discover/validate-integration and lib/project keep resolving `api/template/template.mjs` unchanged.+@josephfarinadiff --git a/packages/cli/api/template/_adapter.mjs b/packages/cli/api/template/_adapter.mjsnew file mode 100644index 0000000000..0a1239e93a--- /dev/null+++ b/packages/cli/api/template/_adapter.mjs@@ -0,0 +1,666 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Shared discovery + IO for the template command family.+ *+ * This adapter owns everything the template leaves (list/show/skeleton/copy)+ * AND other commands (component, layout, search, init, discover,+ * validate-integration) share: template discovery across core/external/+ * integration sources, the template-spec loaders, and the cross-command+ * helpers (stripTemplateAssetRefs, findShowcase, findRelatedBlocks,+ * extractComponents, listTemplates). The `template.mjs` barrel re-exports the+ * public helpers so external import paths (`api/template/template.mjs`) keep+ * working unchanged.+ *+ * @position api/template — shared discovery/IO under the template leaves;+ * consumed by the leaves and re-exported by the template barrel.+ */++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 '../../schemas/template-schema.mjs';+import {CLI_ROOT, discoverExternalPackages} from '../../utils/paths.mjs';+import {Project} from '../../lib/project.mjs';++/** Identity used for core (built-in) templates in package-scoped listings. */+const CORE_PACKAGE = '@astryxdesign/core';++/**+ * 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+ * @returns {string}+ */+export function pkgOf(t) {+ return t.package ?? CORE_PACKAGE;+}++/**+ * A discovered template (page or block), normalized across core, external, and+ * integration sources. Not every source populates every field, so+ * source-specific extras (`aspectRatio`, `isShowcase`, `package`) are optional.+ * @typedef {object} DiscoveredTemplate+ * @property {'page'|'block'} type+ * @property {string} dirName+ * @property {string} name+ * @property {string} description+ * @property {string} [category]+ * @property {boolean} [isReady]+ * @property {boolean} [scaffold]+ * @property {number} [aspectRatio]+ * @property {string[]} [componentsUsed]+ * @property {boolean} [isShowcase]+ * @property {string} filePath+ * @property {string} docPath+ * @property {string} [package]+ */++/**+ * An integration-template discovery error.+ * @typedef {object} TemplateDiscoveryError+ * @property {string} package+ * @property {string} [template]+ * @property {string} message+ */++/**+ * The loaded metadata object from a template spec (loose — authored shape).+ * @typedef {Record<string, any> | undefined | null} TemplateDocModule+ */++/**+ * 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)$/;++/** @type {ReturnType<typeof createJiti> | undefined} */+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,+ * `.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');+const BLOCKS_DIR = path.join(TEMPLATES_DIR, 'blocks');++/**+ * Inline placeholder swapped in for demo imagery when scaffolding a template,+ * so scaffolded pages render with zero setup (see stripTemplateAssetRefs).+ * Neutral hex colors (not design tokens) so it renders in any project, themed+ * 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';++/**+ * Demo-image sources to strip from scaffolded projects — Meta's lookaside CDN+ * (a Meta-only network dependency). Genuine third-party URLs (e.g. brand logos+ * from paypalobjects.com) are intentionally left untouched.+ *+ * @type {RegExp[]}+ */+const DEMO_IMAGE_PATTERNS = [+ /https?:\/\/(?:[\w-]+\.)*lookaside\.facebook\.com\/[^\s'"`)]+/g,+];++/**+ * Normalize path into Unix path (using forward slashes) for consistent comparison+ * across Windows, macOS, and Linux.+ *+ * @param {string} p - The file path to normalize.+ * @returns {string} The normalized Unix path.+ */+function toPosixPath(p) {+ return p.replace(/\\/g, '/');+}++/**+ * Replace demo image references with a self-contained placeholder data URI so+ * scaffolded pages render with zero setup. Builders drop in their own images.+ *+ * @param {string} source - Template source code.+ * @returns {string} Source with demo image references replaced.+ */+export function stripTemplateAssetRefs(source) {+ return DEMO_IMAGE_PATTERNS.reduce(+ (out, pattern) => out.replace(pattern, PLACEHOLDER_IMAGE),+ 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<TemplateDocModule>}+ */+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;+}++/**+ * List the core page-template directory names (sorted). The `template --list`+ * view discovers far more; this is the minimal core-page set `init` scaffolds+ * from.+ * @returns {string[]}+ */+export function listTemplates() {+ /** @type {string[]} */+ const all = [];+ if (fs.existsSync(PAGES_DIR)) {+ all.push(+ ...fs+ .readdirSync(PAGES_DIR, {withFileTypes: true})+ .filter(e => e.isDirectory())+ .map(e => e.name),+ );+ }+ return all.sort();+}++/**+ * @param {string} dir+ * @param {RegExp} pattern+ * @returns {string[]}+ */+function findDocFiles(dir, pattern) {+ /** @type {string[]} */+ const results = [];+ if (!fs.existsSync(dir)) return results;+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ results.push(...findDocFiles(full, pattern));+ } else if (pattern.test(entry.name)) {+ results.push(full);+ }+ }+ 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+ .readdirSync(PAGES_DIR, {withFileTypes: true})+ .filter(e => e.isDirectory());++ /** @type {DiscoveredTemplate[]} */+ 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);+ templates.push({+ type: 'page',+ dirName: dir.name,+ name: doc?.name || dir.name,+ description: doc?.description || '',+ category: doc?.category || '',+ isReady: doc?.isReady ?? true,+ scaffold: doc?.scaffold ?? false,+ filePath: path.join(dirPath, 'page.tsx'),+ docPath,+ });+ }+ return templates;+}++async function discoverBlocks() {+ const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);+ /** @type {DiscoveredTemplate[]} */+ const blocks = [];+ for (const docPath of docFiles) {+ const suffix = matchedTemplateSuffix(docPath);+ if (!suffix) continue;+ 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);+ const relPath = toPosixPath(path.relative(BLOCKS_DIR, path.dirname(docPath)));+ blocks.push({+ type: 'block',+ dirName: basename,+ name: doc?.name || basename,+ description: doc?.description || '',+ isReady: doc?.isReady ?? true,+ aspectRatio: doc?.aspectRatio ?? 1,+ componentsUsed: doc?.componentsUsed ?? [],+ isShowcase: doc?.isShowcase ?? false,+ filePath: tsxPath,+ docPath,+ category: relPath,+ });+ }+ return blocks;+}+++/**+ * Discover blocks from external packages that declare `astryx.blocks` in+ * their package.json. Same shape as discoverBlocks() output.+ *+ * @param {string} [cwd]+ */+async function discoverExternalBlocks(cwd = process.cwd()) {+ const externals = discoverExternalPackages(cwd);+ /** @type {DiscoveredTemplate[]} */+ const blocks = [];++ for (const ext of externals) {+ if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;+ const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);+ for (const docPath of docFiles) {+ const suffix = matchedTemplateSuffix(docPath);+ if (!suffix) continue;+ 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);+ const relPath = toPosixPath(path.relative(ext.blocksDir, path.dirname(docPath)));+ blocks.push({+ type: 'block',+ dirName: basename,+ name: doc?.name || basename,+ description: doc?.description || '',+ isReady: doc?.isReady ?? true,+ aspectRatio: doc?.aspectRatio ?? 1,+ componentsUsed: doc?.componentsUsed ?? [],+ isShowcase: doc?.isShowcase ?? false,+ filePath: tsxPath,+ docPath,+ category: relPath,+ package: ext.name,+ });+ }+ }++ return blocks;+}++/**+ * Discover all blocks — core + external packages.+ * @param {string} [cwd]+ * @returns {Promise<DiscoveredTemplate[]>}+ */+async function discoverAllBlocks(cwd = process.cwd()) {+ const [core, external] = await Promise.all([+ discoverBlocks(),+ discoverExternalBlocks(cwd),+ ]);+ return [...core, ...external];+}++/**+ * @param {string} [cwd]+ * @returns {Promise<DiscoveredTemplate[]>}+ */+export async function discoverAll(cwd = process.cwd()) {+ const [pages, blocks, integration] = await Promise.all([+ discoverPages(),+ discoverAllBlocks(cwd),+ discoverIntegrationTemplates(cwd),+ ]);+ 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: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}+ */+export 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};+}++/**+ * 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[]}+ */+function findIntegrationDocFiles(root) {+ /** @type {string[]} */+ const results = [];+ if (!fs.existsSync(root)) return results;+ /** @param {string} dir */+ 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 (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {+ results.push(full);+ }+ }+ };+ walk(root);+ return results;+}++/**+ * 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`).+ *+ * @param {string} [cwd]+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}+ */+async function discoverIntegrationTemplates(cwd = process.cwd()) {+ /** @type {DiscoveredTemplate[]} */+ const templates = [];+ /** @type {TemplateDiscoveryError[]} */+ const errors = [];++ let loadedIntegrations;+ try {+ const project = await Project.load(cwd);+ loadedIntegrations =+ /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (+ project.loadedIntegrations+ );+ } catch (err) {+ // A broken astryx.config (or an integration that fails to load) can't+ // contribute templates. Record it as a discovery error instead of+ // swallowing it silently: a bare `catch {}` also hides unexpected bugs.+ // discoverAll (the no-error variant that `astryx template` uses) and+ // Project.templates() both discard this errors array, so the template+ // command's behavior is unchanged — the full config-error UX still lives+ // in `discover`/`doctor` via Project.issues(). Only callers that opt into+ // errors (discoverAllWithErrors) now see the signal.+ errors.push({+ package: 'astryx.config',+ message: err instanceof Error ? err.message : String(err),+ });+ 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: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}+ */+export async function discoverIntegrationTemplatesForOne(integration) {+ /** @type {DiscoveredTemplate[]} */+ const templates = [];+ /** @type {TemplateDiscoveryError[]} */+ 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 = matchedTemplateSuffix(docPath);+ if (!suffix) continue;+ 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: ${/** @type {any} */ (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};+}++/**+ * @param {string} componentName+ * @param {string} [cwd]+ * @returns {Promise<DiscoveredTemplate[]>}+ */+export async function findRelatedBlocks(componentName, cwd) {+ const blocks = await discoverAllBlocks(cwd);+ return blocks.filter(b =>+ (b.componentsUsed ?? []).some(c => c.toLowerCase() === componentName.toLowerCase()),+ );+}++/**+ * @param {string} componentName+ * @param {string} [cwd]+ * @param {{ package?: string }} [options] - When set, only search blocks from this package.+ * Core blocks have no `package` field; external blocks have `package` set to the npm name.+ */+export async function findShowcase(componentName, cwd, options) {+ const blocks = await discoverAllBlocks(cwd);+ const lc = componentName.toLowerCase();+ const packageFilter = options?.package;++ // When scoped to a package, only consider blocks from that package.+ // Core blocks have no `package` field — filter them out when a package is specified.+ const showcases = blocks.filter(b => {+ if (!b.isShowcase) return false;+ if (packageFilter) return b.package === packageFilter;+ return true;+ });++ const toResult = (/** @type {DiscoveredTemplate} */ b) => ({+ name: b.name,+ aspectRatio: b.aspectRatio,+ filePath: b.filePath,+ docPath: b.docPath,+ });++ // Priority 1: own directory (components/Badge/ for "Badge")+ const dirMatch = showcases.find(b => {+ const catDir = path.basename(b.category ?? '').toLowerCase();+ return catDir === lc;+ });+ if (dirMatch) return toResult(dirMatch);++ // Priority 2: componentsUsed in any directory (ClickableCard in Card/)+ const usedMatch = showcases.find(b =>+ (b.componentsUsed ?? []).some(c => c.toLowerCase() === lc),+ );+ if (usedMatch) return toResult(usedMatch);++ return null;+}++const UBIQUITOUS = new Set([+ 'Text',+ 'Heading',+ 'Button',+ 'HStack',+ 'VStack',+ 'Link',+ 'StackItem',+ 'Icon',+]);++/**+ * @param {string} pagePath+ * @returns {string[]}+ */+export function extractComponents(pagePath) {+ const src = fs.readFileSync(pagePath, 'utf-8');+ // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.+ // Templates author bare component names post un-prefix migration+ // (P2380608025), so the `XDS` prefix is optional. Anchoring on the `<`+ // JSX-tag boundary keeps this precise (avoids matching imports/comments/+ // identifiers) while remaining prefix-agnostic.+ const tagRegex = /<(XDS)?([A-Z]\w+)/g;+ /** @type {string[]} */+ const matches = [];+ let m;+ 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();+}diff --git a/packages/cli/api/template/copy/copy.mjs b/packages/cli/api/template/copy/copy.mjsnew file mode 100644index 0000000000..f8d7b3e721--- /dev/null+++ b/packages/cli/api/template/copy/copy.mjs@@ -0,0 +1,94 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `template.copy` leaf — scaffold a resolved template into the project+ * (side effect) and return a `template.copy` receipt.+ *+ * @position api/template/copy — the only side-effecting template leaf: resolves+ * a path-safe destination, strips demo asset refs, writes the file, and+ * returns the receipt. The template dispatcher routes the copy case here.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {+ assertWithin,+ isFilePathArg,+ PathSafetyError,+} from '../../../utils/path-safety.mjs';+import {AstryxError} from '../../error.mjs';+import {ERROR_CODES} from '../../../lib/error-codes.mjs';+import {stripTemplateAssetRefs} from '../_adapter.mjs';++/**+ * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and+ * return the `template.copy` receipt.+ * @param {import('../_adapter.mjs').DiscoveredTemplate} match+ * @param {{targetPath: string, cwd: string}} ctx+ * @returns {import('../../../types/template').TemplateCopyResponse}+ */+export function templateCopy(match, {targetPath, cwd}) {+ if (!fs.existsSync(match.filePath)) {+ throw new AstryxError(+ `No source file found for template "${match.dirName}"`,+ undefined,+ ERROR_CODES.ERR_NO_SOURCE,+ );+ }++ // Path-safety: resolve the user-supplied targetPath relative to cwd,+ // rejecting absolute paths and any traversal that escapes the project+ // root. This guard runs BEFORE any mkdir/copyFile so we never create+ // directories outside the root just to fail on the file write.+ let resolvedTarget;+ try {+ resolvedTarget = assertWithin(targetPath, cwd, {+ label: 'template target path',+ });+ } catch (err) {+ if (err instanceof PathSafetyError) {+ throw new AstryxError(+ err.message,+ undefined,+ ERROR_CODES.ERR_PATH_TRAVERSAL,+ );+ }+ throw err;+ }++ // If targetPath looks like a file (e.g. `./foo.tsx`), write directly to+ // it. Previously this path was treated as a directory and the file was+ // written as `./foo.tsx/page.tsx`, which is wrong and surprising.+ let outputDir;+ let outputFileName;+ let outputFilePath;+ if (isFilePathArg(targetPath)) {+ outputDir = path.dirname(resolvedTarget);+ outputFileName = path.basename(resolvedTarget);+ outputFilePath = resolvedTarget;+ } else {+ outputDir = resolvedTarget;+ outputFileName =+ match.type === 'block' ? path.basename(match.filePath) : 'page.tsx';+ outputFilePath = path.join(outputDir, outputFileName);+ }++ fs.mkdirSync(outputDir, {recursive: true});++ // Strip demo image references so the scaffolded file renders without a+ // Meta-only network dependency.+ const source = fs.readFileSync(match.filePath, 'utf-8');+ const outputSource = stripTemplateAssetRefs(source);+ fs.writeFileSync(outputFilePath, outputSource);++ const relOutput = path.relative(cwd, outputDir) || '.';+ return {+ type: 'template.copy',+ data: {+ template: match.dirName,+ outputDir: relOutput,+ fileName: outputFileName,+ filesCopied: 1,+ },+ };+}diff --git a/packages/cli/api/template/list/list.mjs b/packages/cli/api/template/list/list.mjsnew file mode 100644index 0000000000..7cfdde1c01--- /dev/null+++ b/packages/cli/api/template/list/list.mjs@@ -0,0 +1,44 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `template.list` leaf — list discovered templates (page + block),+ * optionally narrowed by `--type` / `--package`.+ *+ * @position api/template/list — pure projection over an already-discovered+ * template set; the template dispatcher routes `--list` (and the no-name,+ * no-skeleton default) here.+ */++import {pkgOf} from '../_adapter.mjs';++/**+ * Project a discovered template set into the `template.list` envelope.+ * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates+ * @param {{type?: 'page' | 'block', package?: string}} [options]+ * @returns {import('../../../types/template').TemplateListResponse}+ */+export function templateList(templates, options = {}) {+ const {type, package: packageFilter} = options;+ let filtered = templates;+ 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 => ({+ 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,+ // Discovery always sets isReady (defaulting to true), so `?? true` never+ // changes the emitted value — it only satisfies the required-boolean+ // field type where the DiscoveredTemplate typedef leaves it optional.+ isReady: t.isReady ?? true,+ scaffold: t.scaffold ?? false,+ })),+ };+}diff --git a/packages/cli/api/template/show/show.mjs b/packages/cli/api/template/show/show.mjsnew file mode 100644index 0000000000..fcf0862599--- /dev/null+++ b/packages/cli/api/template/show/show.mjs@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `template.show` leaf — return a resolved template's raw source plus the+ * components it composes.+ *+ * @position api/template/show — reads the resolved match's source file; the+ * template dispatcher routes `show` (and the no-target-path default) here.+ */++import * as fs from 'node:fs';+import {AstryxError} from '../../error.mjs';+import {ERROR_CODES} from '../../../lib/error-codes.mjs';+import {extractComponents} from '../_adapter.mjs';++/**+ * Build the `template.show` envelope for an already-resolved template.+ * @param {import('../_adapter.mjs').DiscoveredTemplate} match+ * @returns {import('../../../types/template').TemplateShowResponse}+ */+export function templateShow(match) {+ if (!fs.existsSync(match.filePath)) {+ throw new AstryxError(+ `No source file found for template "${match.dirName}"`,+ undefined,+ ERROR_CODES.ERR_NO_SOURCE,+ );+ }++ return {+ type: 'template.show',+ data: {+ template: match.dirName,+ description: match.description,+ type: match.type,+ components: extractComponents(match.filePath),+ source: fs.readFileSync(match.filePath, 'utf-8'),+ },+ };+}diff --git a/packages/cli/api/template/skeleton/skeleton.mjs b/packages/cli/api/template/skeleton/skeleton.mjsnew file mode 100644index 0000000000..cda22739e2--- /dev/null+++ b/packages/cli/api/template/skeleton/skeleton.mjs@@ -0,0 +1,256 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `template.skeleton` leaf — a layout skeleton (structural tags with+ * spatial annotations) plus the components a resolved template composes.+ *+ * @position api/template/skeleton — derives a compact layout reference from the+ * resolved match's source; the template dispatcher routes `--skeleton` here.+ */++import * as fs from 'node:fs';+import {AstryxError} from '../../error.mjs';+import {ERROR_CODES} from '../../../lib/error-codes.mjs';+import {extractComponents} from '../_adapter.mjs';++const STRUCTURAL = new Set([+ '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) {+ /** @type {string[]} */+ const attrs = [];+ for (const name of SPATIAL_PROPS) {+ const eqMatch = tagText.match(new RegExp(`\\b${name}\\s*=\\s*`));+ if (eqMatch && eqMatch.index != null) {+ 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;+}++/**+ * @param {string} source+ * @returns {string}+ */+function extractSkeleton(source) {+ const lines = source.split('\n');+ /** @type {string[]} */+ const out = [];+ let depth = 0;+ let capturing = false;+ let inDefaultExport = false;+ const MAX_LINES = 35;+ /** @type {string[]} */+ const depthStack = [];++ 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 (!capturing) continue;+ if (out.length >= MAX_LINES) {+ if (!out[out.length - 1]?.includes('...'))+ out.push(' '.repeat(depth) + '...');+ continue;+ }++ // Match a JSX opening tag, e.g. `<Section` or the legacy `<XDSSection`.+ // The `XDS` prefix is optional (templates author bare names post+ // un-prefix migration P2380608025). `tagName` is the full authored name+ // (used for the self-closing lookahead); `comp` is the bare display name.+ const openMatch = t.match(/^<((XDS)?([A-Z]\w+))/);+ if (openMatch && !t.startsWith('</')) {+ const tagName = openMatch[1];+ const comp = openMatch[3];+ let tagText = '';+ for (let j = i; j < Math.min(i + 12, lines.length); j++) {+ tagText += ' ' + lines[j];+ if (lines[j].includes('>')) break;+ }++ 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'),+ );++ if (isVStack && !hasSpatialProps) continue;++ if (isSelfClosing) {+ out.push(' '.repeat(depth) + `<${comp}${propStr} />`);+ } else if (STRUCTURAL.has(comp) || (isVStack && hasSpatialProps)) {+ out.push(' '.repeat(depth) + `<${comp}${propStr}>`);+ depthStack.push(comp);+ depth++;+ } else {+ out.push(' '.repeat(depth) + `<${comp}${propStr} />`);+ }+ continue;+ }++ const closeMatch = t.match(/^<\/(XDS)?([A-Z]\w+)>/);+ if (closeMatch) {+ const comp = closeMatch[2];+ if (depthStack.length > 0 && depthStack[depthStack.length - 1] === comp) {+ depthStack.pop();+ depth = Math.max(0, depth - 1);+ out.push(' '.repeat(depth) + `</${comp}>`);+ }+ continue;+ }++ 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:'))+ ) {+ const styleProps = [];+ const divText = lines.slice(i, Math.min(i + 5, lines.length)).join(' ');+ const pp = divText.match(/padding[^:]*:\s*['"]?([^'"},)]+)/);+ const mw = divText.match(/maxWidth:\s*(\d+)/);+ const gp = divText.match(/gap:\s*(\d+)/);+ const mg = divText.match(/margin:\s*['"]([^'"]+)['"]/);+ const mi = divText.match(/marginInline:\s*['"]([^'"]+)['"]/);+ if (pp) styleProps.push(`padding: ${pp[1].trim()}`);+ if (mw) styleProps.push(`maxWidth: ${mw[1]}`);+ if (gp) styleProps.push(`gap: ${gp[1]}`);+ if (mg) styleProps.push(`margin: ${mg[1]}`);+ if (mi) styleProps.push(`marginInline: ${mi[1]}`);+ if (styleProps.length > 0) {+ out.push(' '.repeat(depth) + `/* div: ${styleProps.join(', ')} */`);+ }+ }+ }++ return out.filter(l => l.trim()).join('\n');+}++/**+ * Build the `template.skeleton` envelope for an already-resolved template.+ * `match` may be undefined when `--skeleton` is run without a name — the same+ * "specify a template name" error the dispatcher's resolution would surface.+ * @param {import('../_adapter.mjs').DiscoveredTemplate | undefined} match+ * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates+ * @returns {import('../../../types/template').TemplateSkeletonResponse}+ */+export function templateSkeleton(match, templates) {+ if (!match) {+ throw new AstryxError(+ 'Specify a template name for --skeleton',+ templates.map(t => ({name: t.dirName, reason: `${t.type} template`})),+ ERROR_CODES.ERR_UNKNOWN_TEMPLATE,+ );+ }+ if (!fs.existsSync(match.filePath)) {+ throw new AstryxError(+ `No source file found for template "${match.dirName}"`,+ undefined,+ ERROR_CODES.ERR_NO_SOURCE,+ );+ }+ const src = fs.readFileSync(match.filePath, 'utf-8');+ return {+ type: 'template.skeleton',+ data: {+ template: match.dirName,+ description: match.description,+ components: extractComponents(match.filePath),+ skeleton: extractSkeleton(src),+ },+ };+}diff --git a/packages/cli/api/template/template.mjs b/packages/cli/api/template/template.mjsindex 1604a47620..845a943a0e 100644--- a/packages/cli/api/template/template.mjs+++ b/packages/cli/api/template/template.mjs@@ -2,859 +2,52 @@/*** @file Programmatic API for the template command.- */--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 '../../schemas/template-schema.mjs';-import {CLI_ROOT, discoverExternalPackages} from '../../utils/paths.mjs';-import {- assertWithin,- isFilePathArg,- PathSafetyError,-} from '../../utils/path-safety.mjs';-import {AstryxError} from '../error.mjs';-import {ERROR_CODES} from '../../lib/error-codes.mjs';-import {Project} from '../../lib/project.mjs';--/** Identity used for core (built-in) templates in package-scoped listings. */-const CORE_PACKAGE = '@astryxdesign/core';--/**- * A discovered template (page or block), normalized across core, external, and- * integration sources. Not every source populates every field, so- * source-specific extras (`aspectRatio`, `isShowcase`, `package`) are optional.- * @typedef {object} DiscoveredTemplate- * @property {'page'|'block'} type- * @property {string} dirName- * @property {string} name- * @property {string} description- * @property {string} [category]- * @property {boolean} [isReady]- * @property {boolean} [scaffold]- * @property {number} [aspectRatio]- * @property {string[]} [componentsUsed]- * @property {boolean} [isShowcase]- * @property {string} filePath- * @property {string} docPath- * @property {string} [package]- */--/**- * An integration-template discovery error.- * @typedef {object} TemplateDiscoveryError- * @property {string} package- * @property {string} [template]- * @property {string} message- */--/**- * The loaded metadata object from a template spec (loose — authored shape).- * @typedef {Record<string, any> | undefined | null} TemplateDocModule- */--/**- * 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)$/;--/** @type {ReturnType<typeof createJiti> | undefined} */-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,- * `.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');-const BLOCKS_DIR = path.join(TEMPLATES_DIR, 'blocks');--/**- * Inline placeholder swapped in for demo imagery when scaffolding a template,- * so scaffolded pages render with zero setup (see stripTemplateAssetRefs).- * Neutral hex colors (not design tokens) so it renders in any project, themed- * 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';--/**- * Demo-image sources to strip from scaffolded projects — Meta's lookaside CDN- * (a Meta-only network dependency). Genuine third-party URLs (e.g. brand logos- * from paypalobjects.com) are intentionally left untouched.- *- * @type {RegExp[]}- */-const DEMO_IMAGE_PATTERNS = [- /https?:\/\/(?:[\w-]+\.)*lookaside\.facebook\.com\/[^\s'"`)]+/g,-];--/**- * Normalize path into Unix path (using forward slashes) for consistent comparison- * across Windows, macOS, and Linux.- *- * @param {string} p - The file path to normalize.- * @returns {string} The normalized Unix path.- */-function toPosixPath(p) {- return p.replace(/\\/g, '/');-}--/**- * Replace demo image references with a self-contained placeholder data URI so- * scaffolded pages render with zero setup. Builders drop in their own images.- *- * @param {string} source - Template source code.- * @returns {string} Source with demo image references replaced.- */-export function stripTemplateAssetRefs(source) {- return DEMO_IMAGE_PATTERNS.reduce(- (out, pattern) => out.replace(pattern, PLACEHOLDER_IMAGE),- 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<TemplateDocModule>}- */-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;-}---export {discoverAll as discoverTemplates};--export function listTemplates() {- /** @type {string[]} */- const all = [];- if (fs.existsSync(PAGES_DIR)) {- all.push(- ...fs- .readdirSync(PAGES_DIR, {withFileTypes: true})- .filter(e => e.isDirectory())- .map(e => e.name),- );- }- return all.sort();-}--/**- * @param {string} dir- * @param {RegExp} pattern- * @returns {string[]}- */-function findDocFiles(dir, pattern) {- /** @type {string[]} */- const results = [];- if (!fs.existsSync(dir)) return results;- for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {- const full = path.join(dir, entry.name);- if (entry.isDirectory()) {- results.push(...findDocFiles(full, pattern));- } else if (pattern.test(entry.name)) {- results.push(full);- }- }- 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- .readdirSync(PAGES_DIR, {withFileTypes: true})- .filter(e => e.isDirectory());-- /** @type {DiscoveredTemplate[]} */- 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);- templates.push({- type: 'page',- dirName: dir.name,- name: doc?.name || dir.name,- description: doc?.description || '',- category: doc?.category || '',- isReady: doc?.isReady ?? true,- scaffold: doc?.scaffold ?? false,- filePath: path.join(dirPath, 'page.tsx'),- docPath,- });- }- return templates;-}--async function discoverBlocks() {- const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);- /** @type {DiscoveredTemplate[]} */- const blocks = [];- for (const docPath of docFiles) {- const suffix = matchedTemplateSuffix(docPath);- if (!suffix) continue;- 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);- const relPath = toPosixPath(path.relative(BLOCKS_DIR, path.dirname(docPath)));- blocks.push({- type: 'block',- dirName: basename,- name: doc?.name || basename,- description: doc?.description || '',- isReady: doc?.isReady ?? true,- aspectRatio: doc?.aspectRatio ?? 1,- componentsUsed: doc?.componentsUsed ?? [],- isShowcase: doc?.isShowcase ?? false,- filePath: tsxPath,- docPath,- category: relPath,- });- }- return blocks;-}---/**- * Discover blocks from external packages that declare `astryx.blocks` in- * their package.json. Same shape as discoverBlocks() output.+ * This module is BOTH the template dispatcher and the stable import surface for+ * the template family. `template()` discovers the available templates, resolves+ * the requested one, and routes to a leaf (list/show/skeleton/copy). The shared+ * discovery/IO + cross-command helpers live in `./_adapter.mjs` and are+ * RE-EXPORTED here so external import paths (`api/template/template.mjs`) —+ * used by component, layout, search, init, discover, validate-integration, and+ * lib/project — keep resolving unchanged.*- * @param {string} [cwd]+ * @position api/template — the template dispatcher + barrel; leaves live under+ * ./list, ./show, ./skeleton, ./copy and shared discovery under ./_adapter.*/-async function discoverExternalBlocks(cwd = process.cwd()) {- const externals = discoverExternalPackages(cwd);- /** @type {DiscoveredTemplate[]} */- const blocks = [];-- for (const ext of externals) {- if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;- const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);- for (const docPath of docFiles) {- const suffix = matchedTemplateSuffix(docPath);- if (!suffix) continue;- 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);- const relPath = toPosixPath(path.relative(ext.blocksDir, path.dirname(docPath)));- blocks.push({- type: 'block',- dirName: basename,- name: doc?.name || basename,- description: doc?.description || '',- isReady: doc?.isReady ?? true,- aspectRatio: doc?.aspectRatio ?? 1,- componentsUsed: doc?.componentsUsed ?? [],- isShowcase: doc?.isShowcase ?? false,- filePath: tsxPath,- docPath,- category: relPath,- package: ext.name,- });- }- }- return blocks;-}--/**- * Discover all blocks — core + external packages.- * @param {string} [cwd]- * @returns {Promise<DiscoveredTemplate[]>}- */-async function discoverAllBlocks(cwd = process.cwd()) {- const [core, external] = await Promise.all([- discoverBlocks(),- discoverExternalBlocks(cwd),- ]);- return [...core, ...external];-}--/**- * @param {string} [cwd]- * @returns {Promise<DiscoveredTemplate[]>}- */-async function discoverAll(cwd = process.cwd()) {- const [pages, blocks, integration] = await Promise.all([- discoverPages(),- discoverAllBlocks(cwd),- discoverIntegrationTemplates(cwd),- ]);- 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: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}- */-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-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[]}- */-function findIntegrationDocFiles(root) {- /** @type {string[]} */- const results = [];- if (!fs.existsSync(root)) return results;- /** @param {string} dir */- 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 (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {- results.push(full);- }- }- };- walk(root);- return results;-}--/**- * 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`).- *- * @param {string} [cwd]- * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}- */-async function discoverIntegrationTemplates(cwd = process.cwd()) {- /** @type {DiscoveredTemplate[]} */- const templates = [];- /** @type {TemplateDiscoveryError[]} */- const errors = [];-- let loadedIntegrations;- try {- const project = await Project.load(cwd);- loadedIntegrations =- /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (- project.loadedIntegrations- );- } catch (err) {- // A broken astryx.config (or an integration that fails to load) can't- // contribute templates. Record it as a discovery error instead of- // swallowing it silently: a bare `catch {}` also hides unexpected bugs.- // discoverAll (the no-error variant that `astryx template` uses) and- // Project.templates() both discard this errors array, so the template- // command's behavior is unchanged — the full config-error UX still lives- // in `discover`/`doctor` via Project.issues(). Only callers that opt into- // errors (discoverAllWithErrors) now see the signal.- errors.push({- package: 'astryx.config',- message: err instanceof Error ? err.message : String(err),- });- 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: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}- */-export async function discoverIntegrationTemplatesForOne(integration) {- /** @type {DiscoveredTemplate[]} */- const templates = [];- /** @type {TemplateDiscoveryError[]} */- 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 = matchedTemplateSuffix(docPath);- if (!suffix) continue;- 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: ${/** @type {any} */ (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};-}--/**- * @param {string} componentName- * @param {string} [cwd]- * @returns {Promise<DiscoveredTemplate[]>}- */-export async function findRelatedBlocks(componentName, cwd) {- const blocks = await discoverAllBlocks(cwd);- return blocks.filter(b =>- (b.componentsUsed ?? []).some(c => c.toLowerCase() === componentName.toLowerCase()),- );-}--/**- * @param {string} componentName- * @param {string} [cwd]- * @param {{ package?: string }} [options] - When set, only search blocks from this package.- * Core blocks have no `package` field; external blocks have `package` set to the npm name.- */-export async function findShowcase(componentName, cwd, options) {- const blocks = await discoverAllBlocks(cwd);- const lc = componentName.toLowerCase();- const packageFilter = options?.package;-- // When scoped to a package, only consider blocks from that package.- // Core blocks have no `package` field — filter them out when a package is specified.- const showcases = blocks.filter(b => {- if (!b.isShowcase) return false;- if (packageFilter) return b.package === packageFilter;- return true;- });-- const toResult = (/** @type {DiscoveredTemplate} */ b) => ({- name: b.name,- aspectRatio: b.aspectRatio,- filePath: b.filePath,- docPath: b.docPath,- });-- // Priority 1: own directory (components/Badge/ for "Badge")- const dirMatch = showcases.find(b => {- const catDir = path.basename(b.category ?? '').toLowerCase();- return catDir === lc;- });- if (dirMatch) return toResult(dirMatch);-- // Priority 2: componentsUsed in any directory (ClickableCard in Card/)- const usedMatch = showcases.find(b =>- (b.componentsUsed ?? []).some(c => c.toLowerCase() === lc),- );- if (usedMatch) return toResult(usedMatch);-- return null;-}+import {discoverAll, pkgOf} from './_adapter.mjs';+import {AstryxError} from '../error.mjs';+import {ERROR_CODES} from '../../lib/error-codes.mjs';+import {templateList} from './list/list.mjs';+import {templateShow} from './show/show.mjs';+import {templateSkeleton} from './skeleton/skeleton.mjs';+import {templateCopy} from './copy/copy.mjs';-const UBIQUITOUS = new Set([- 'Text',- 'Heading',- 'Button',- 'HStack',- 'VStack',- 'Link',- 'StackItem',- 'Icon',-]);+// Re-export the shared discovery/IO + cross-command helpers so this module+// stays the single import surface for the template family (same exports as+// before the leaf split). `discoverAll` is exposed both under its own name and+// the historical `discoverTemplates` alias.+export {+ discoverAll,+ discoverAll as discoverTemplates,+ discoverAllWithErrors,+ discoverIntegrationTemplatesForOne,+ stripTemplateAssetRefs,+ listTemplates,+ findRelatedBlocks,+ findShowcase,+ extractComponents,+} from './_adapter.mjs';/**- * @param {string} pagePath- * @returns {string[]}+ * @typedef {import('./_adapter.mjs').DiscoveredTemplate} DiscoveredTemplate*/-export function extractComponents(pagePath) {- const src = fs.readFileSync(pagePath, 'utf-8');- // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.- // Templates author bare component names post un-prefix migration- // (P2380608025), so the `XDS` prefix is optional. Anchoring on the `<`- // JSX-tag boundary keeps this precise (avoids matching imports/comments/- // identifiers) while remaining prefix-agnostic.- const tagRegex = /<(XDS)?([A-Z]\w+)/g;- /** @type {string[]} */- const matches = [];- let m;- 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();-}--const STRUCTURAL = new Set([- '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[]}+ * @typedef {import('./_adapter.mjs').TemplateDiscoveryError} TemplateDiscoveryError*/-function extractSpatialAttrs(tagText) {- /** @type {string[]} */- const attrs = [];- for (const name of SPATIAL_PROPS) {- const eqMatch = tagText.match(new RegExp(`\\b${name}\\s*=\\s*`));- if (eqMatch && eqMatch.index != null) {- 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;-}-/**- * @param {string} source- * @returns {string}+ * @typedef {import('./_adapter.mjs').TemplateDocModule} TemplateDocModule*/-function extractSkeleton(source) {- const lines = source.split('\n');- /** @type {string[]} */- const out = [];- let depth = 0;- let capturing = false;- let inDefaultExport = false;- const MAX_LINES = 35;- /** @type {string[]} */- const depthStack = [];-- 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 (!capturing) continue;- if (out.length >= MAX_LINES) {- if (!out[out.length - 1]?.includes('...'))- out.push(' '.repeat(depth) + '...');- continue;- }-- // Match a JSX opening tag, e.g. `<Section` or the legacy `<XDSSection`.- // The `XDS` prefix is optional (templates author bare names post- // un-prefix migration P2380608025). `tagName` is the full authored name- // (used for the self-closing lookahead); `comp` is the bare display name.- const openMatch = t.match(/^<((XDS)?([A-Z]\w+))/);- if (openMatch && !t.startsWith('</')) {- const tagName = openMatch[1];- const comp = openMatch[3];- let tagText = '';- for (let j = i; j < Math.min(i + 12, lines.length); j++) {- tagText += ' ' + lines[j];- if (lines[j].includes('>')) break;- }-- 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'),- );-- if (isVStack && !hasSpatialProps) continue;-- if (isSelfClosing) {- out.push(' '.repeat(depth) + `<${comp}${propStr} />`);- } else if (STRUCTURAL.has(comp) || (isVStack && hasSpatialProps)) {- out.push(' '.repeat(depth) + `<${comp}${propStr}>`);- depthStack.push(comp);- depth++;- } else {- out.push(' '.repeat(depth) + `<${comp}${propStr} />`);- }- continue;- }-- const closeMatch = t.match(/^<\/(XDS)?([A-Z]\w+)>/);- if (closeMatch) {- const comp = closeMatch[2];- if (depthStack.length > 0 && depthStack[depthStack.length - 1] === comp) {- depthStack.pop();- depth = Math.max(0, depth - 1);- out.push(' '.repeat(depth) + `</${comp}>`);- }- continue;- }-- 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:'))- ) {- const styleProps = [];- const divText = lines.slice(i, Math.min(i + 5, lines.length)).join(' ');- const pp = divText.match(/padding[^:]*:\s*['"]?([^'"},)]+)/);- const mw = divText.match(/maxWidth:\s*(\d+)/);- const gp = divText.match(/gap:\s*(\d+)/);- const mg = divText.match(/margin:\s*['"]([^'"]+)['"]/);- const mi = divText.match(/marginInline:\s*['"]([^'"]+)['"]/);- if (pp) styleProps.push(`padding: ${pp[1].trim()}`);- if (mw) styleProps.push(`maxWidth: ${mw[1]}`);- if (gp) styleProps.push(`gap: ${gp[1]}`);- if (mg) styleProps.push(`margin: ${mg[1]}`);- if (mi) styleProps.push(`marginInline: ${mi[1]}`);- if (styleProps.length > 0) {- out.push(' '.repeat(depth) + `/* div: ${styleProps.join(', ')} */`);- }- }- }-- return out.filter(l => l.trim()).join('\n');-}/*** @param {string} [name]@@ -880,33 +73,8 @@ export async function template(name, options = {}) {} = 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 = filtered.filter(t => t.type === type);- if (packageFilter) filtered = filtered.filter(t => pkgOf(t) === packageFilter);- return {- type: 'template.list',- data: filtered.map(t => ({- 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,- })),- };+ return templateList(templates, {type, package: packageFilter});}// Resolve `name` to a single template. The same id can appear across types@@ -936,106 +104,12 @@ export async function template(name, options = {}) {const match = candidates[0];if (skeleton) {- if (!match) {- throw new AstryxError(- 'Specify a template name for --skeleton',- templates.map(t => ({name: t.dirName, reason: `${t.type} template`})),- ERROR_CODES.ERR_UNKNOWN_TEMPLATE,- );- }- if (!fs.existsSync(match.filePath)) {- 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 {- type: 'template.skeleton',- data: {- template: name,- description: match.description,- components: extractComponents(match.filePath),- skeleton: extractSkeleton(src),- },- };- }-- if (!fs.existsSync(match.filePath)) {- throw new AstryxError(- `No source file found for template "${name}"`,- undefined,- ERROR_CODES.ERR_NO_SOURCE,- );+ return templateSkeleton(match, templates);}if (show || !targetPath) {- return {- type: 'template.show',- data: {- template: name,- description: match.description,- type: match.type,- components: extractComponents(match.filePath),- source: fs.readFileSync(match.filePath, 'utf-8'),- },- };+ return templateShow(match);}- // Path-safety: resolve the user-supplied targetPath relative to cwd,- // rejecting absolute paths and any traversal that escapes the project- // root. This guard runs BEFORE any mkdir/copyFile so we never create- // directories outside the root just to fail on the file write.- let resolvedTarget;- try {- resolvedTarget = assertWithin(targetPath, cwd, {- label: 'template target path',- });- } catch (err) {- if (err instanceof PathSafetyError) {- throw new AstryxError(- err.message,- undefined,- ERROR_CODES.ERR_PATH_TRAVERSAL,- );- }- throw err;- }-- // If targetPath looks like a file (e.g. `./foo.tsx`), write directly to- // it. Previously this path was treated as a directory and the file was- // written as `./foo.tsx/page.tsx`, which is wrong and surprising.- let outputDir;- let outputFileName;- let outputFilePath;- if (isFilePathArg(targetPath)) {- outputDir = path.dirname(resolvedTarget);- outputFileName = path.basename(resolvedTarget);- outputFilePath = resolvedTarget;- } else {- outputDir = resolvedTarget;- outputFileName =- match.type === 'block' ? path.basename(match.filePath) : 'page.tsx';- outputFilePath = path.join(outputDir, outputFileName);- }-- fs.mkdirSync(outputDir, {recursive: true});-- // Strip demo image references so the scaffolded file renders without a- // Meta-only network dependency.- const source = fs.readFileSync(match.filePath, 'utf-8');- const outputSource = stripTemplateAssetRefs(source);- fs.writeFileSync(outputFilePath, outputSource);-- const relOutput = path.relative(cwd, outputDir) || '.';- return {- type: 'template.copy',- data: {- template: name,- outputDir: relOutput,- fileName: outputFileName,- filesCopied: 1,- },- };+ return templateCopy(match, {targetPath, cwd});}