@astryxdesign/cli 0.7.12-canary.f36bd72 → 0.7.12

package/clients/cli/commands/template.mjs

@@ -5,7 +5,14 @@
  */
 
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, text, records, code, record} from '../formatters/index.mjs';
+import {
+  emit,
+  section,
+  text,
+  records,
+  code,
+  record,
+} from '../formatters/index.mjs';
 import {cliError, rejectEmptyArgument} from '../lib/cli-error.mjs';
 import {template as templateApi} from '../../../api/template/template.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
@@ -16,7 +23,10 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
 import {doc as templateCommand} from './template.doc.mjs';
 import {doc as templateFn} from '../../../api/template/template.doc.mjs';
 
-export {discoverTemplates, listTemplates} from '../../../api/template/template.mjs';
+export {
+  discoverTemplates,
+  listTemplates,
+} from '../../../api/template/template.mjs';
 
 /**
  * The discriminated response returned by the template API. The api layer
@@ -112,94 +122,134 @@ export function registerTemplate(program) {
        * @param {{list?: boolean, type?: string, package?: string, skeleton?: boolean, cdn?: boolean | string, overwrite?: boolean}} options
        */
       async (name, targetPath, options) => {
-      const usesName = !options.cdn && !options.list;
-      const usesPath = options.cdn
-        ? typeof options.cdn !== 'string'
-        : !options.list && !options.skeleton;
-      if (usesName) rejectEmptyArgument('name', name, 'astryx template');
-      if (usesPath) rejectEmptyArgument('path', targetPath, 'astryx template');
-      const json = program.opts().json || false;
-      const run = getCliInvocation();
+        const usesName = !options.cdn && !options.list;
+        const usesPath = options.cdn
+          ? typeof options.cdn !== 'string'
+          : !options.list && !options.skeleton;
+        if (usesName) rejectEmptyArgument('name', name, 'astryx template');
+        if (usesPath)
+          rejectEmptyArgument('path', targetPath, 'astryx template');
+        const json = program.opts().json || false;
+        const run = getCliInvocation();
 
-      // Non-blocking nudge: if any configured integration has validation
-      // issues, print one compact line to stderr pointing at
-      // doctor integration validate. Best-effort; suppressed in --json mode.
-      try {
-        const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project, {json});
-      } catch {
-        // Never let the nudge break the command.
-      }
+        // Non-blocking nudge: if any configured integration has validation
+        // issues, print one compact line to stderr pointing at
+        // doctor integration validate. Best-effort; suppressed in --json mode.
+        try {
+          const project = await Project.load(process.cwd());
+          await warnOnIntegrationIssues(project, {json});
+        } catch {
+          // Never let the nudge break the command.
+        }
 
-      /** @type {TemplateResponse} */
-      let result;
-      try {
-        result = /** @type {TemplateResponse} */ (
-          await templateApi(name, {
-            list: options.list,
-            skeleton: options.skeleton,
-            cdn: options.cdn,
-            type: /** @type {'page' | 'block' | undefined} */ (options.type),
-            package: options.package,
-            targetPath,
-            overwrite: options.overwrite,
-            cwd: process.cwd(),
-          })
-        );
-      } catch (e) {
-        // template API throws structured errors with {name, reason} suggestions —
-        // pass them through untouched so the CLI envelope matches the API.
-        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
-        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
-      }
+        /** @type {TemplateResponse} */
+        let result;
+        try {
+          result = /** @type {TemplateResponse} */ (
+            await templateApi(name, {
+              list: options.list,
+              skeleton: options.skeleton,
+              cdn: options.cdn,
+              type: /** @type {'page' | 'block' | undefined} */ (options.type),
+              package: options.package,
+              targetPath,
+              overwrite: options.overwrite,
+              cwd: process.cwd(),
+            })
+          );
+        } catch (e) {
+          // template API throws structured errors with {name, reason} suggestions —
+          // pass them through untouched so the CLI envelope matches the API.
+          const err =
+            /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+          return cliError(err.message, {
+            suggestions: err.suggestions || [],
+            code: err.code,
+          });
+        }
 
-      const answered = summarize(result);
-      if (json) {
-        jsonOut(result);
-        return answered;
-      }
+        const answered = summarize(result);
+        if (json) {
+          jsonOut(result);
+          return answered;
+        }
 
-      switch (result.type) {
-        case 'template.list': {
-          const pages = result.data.filter(t => t.type === 'page');
-          const blocks = result.data.filter(t => t.type === 'block');
+        switch (result.type) {
+          case 'template.list': {
+            const pages = result.data.filter(t => t.type === 'page');
+            const blocks = result.data.filter(t => t.type === 'block');
 
-          // Bare `template` (no --list, no name) shows a grouped summary so a
-          // no-context agent or terminal doesn't receive 150 KB of catalog. The
-          // full catalog stays reachable via `template --list`.
-          if (!options.list && !name) {
-            /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry[]} items */
-            const grouped = items => {
-              /** @type {Map<string, string[]>} */
-              const groups = new Map();
-              for (const t of items) {
-                const cat = t.category || 'Other';
-                const list = groups.get(cat);
-                if (list) {
-                  list.push(t.id);
-                } else {
-                  groups.set(cat, [t.id]);
+            // Bare `template` (no --list, no name) shows a grouped summary so a
+            // no-context agent or terminal doesn't receive 150 KB of catalog. The
+            // full catalog stays reachable via `template --list`.
+            if (!options.list && !name) {
+              /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry[]} items */
+              const grouped = items => {
+                /** @type {Map<string, string[]>} */
+                const groups = new Map();
+                for (const t of items) {
+                  const cat = t.category || 'Other';
+                  const list = groups.get(cat);
+                  if (list) {
+                    list.push(t.id);
+                  } else {
+                    groups.set(cat, [t.id]);
+                  }
+                }
+                /** @type {string[]} */
+                const lines = [];
+                for (const [cat, ids] of groups) {
+                  lines.push(`${cat}: ${ids.join(', ')}`);
                 }
-              }
-              /** @type {string[]} */
-              const lines = [];
-              for (const [cat, ids] of groups) {
-                lines.push(`${cat}: ${ids.join(', ')}`);
-              }
-              return lines.join('\n');
-            };
+                return lines.join('\n');
+              };
+              emit(
+                pages.length > 0 && section(`Page Templates (${pages.length})`),
+                pages.length > 0 && text(grouped(pages)),
+                blocks.length > 0 &&
+                  section(`Block Templates (${blocks.length})`),
+                blocks.length > 0 && text(grouped(blocks)),
+                section('Usage'),
+                text(
+                  [
+                    `${run} template <id>                  Show full source`,
+                    `${run} template <id> [target-path]     Scaffold page or block`,
+                    `${run} template <id> --skeleton        Layout reference`,
+                    `${run} template --list                 Full catalog with descriptions`,
+                    `${run} template --list --type block    List only blocks`,
+                    `${run} template --list --package <pkg> List from one package`,
+                    `${run} template --cdn                 CDN starter page, no build step`,
+                  ].join('\n'),
+                ),
+              );
+              break;
+            }
+
+            // Project each entry to its JSON-mirroring fields; the WIP marker is
+            // folded into `name` (as before) and the package is shown only when it
+            // isn't the built-in core package.
+            /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
+            const toRow = t => ({
+              id: t.id,
+              name: t.isReady ? t.name : `${t.name} (WIP)`,
+              description: t.description,
+              package:
+                t.package && t.package !== '@astryxdesign/core'
+                  ? t.package
+                  : '',
+              replaces: t.replaces ?? '',
+            });
+            const fields = ['id', 'name', 'description', 'package', 'replaces'];
             emit(
-              pages.length > 0 && section(`Page Templates (${pages.length})`),
-              pages.length > 0 && text(grouped(pages)),
-              blocks.length > 0 && section(`Block Templates (${blocks.length})`),
-              blocks.length > 0 && text(grouped(blocks)),
+              pages.length > 0 && section('Page Templates'),
+              pages.length > 0 && records(pages.map(toRow), {fields}),
+              blocks.length > 0 && section('Block Templates'),
+              blocks.length > 0 && records(blocks.map(toRow), {fields}),
               section('Usage'),
               text(
                 [
-                  `${run} template <id>                  Show full source`,
                   `${run} template <id> [target-path]     Scaffold page or block`,
                   `${run} template <id> --skeleton        Layout reference`,
-                  `${run} template --list                 Full catalog with descriptions`,
                   `${run} template --list --type block    List only blocks`,
                   `${run} template --list --package <pkg> List from one package`,
                   `${run} template --cdn                 CDN starter page, no build step`,
@@ -209,119 +259,92 @@ export function registerTemplate(program) {
             break;
           }
 
-          // Project each entry to its JSON-mirroring fields; the WIP marker is
-          // folded into `name` (as before) and the package is shown only when it
-          // isn't the built-in core package.
-          /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
-          const toRow = t => ({
-            id: t.id,
-            name: t.isReady ? t.name : `${t.name} (WIP)`,
-            description: t.description,
-            package:
-              t.package && t.package !== '@astryxdesign/core' ? t.package : '',
-            replaces: t.replaces ?? '',
-          });
-          const fields = ['id', 'name', 'description', 'package', 'replaces'];
-          emit(
-            pages.length > 0 && section('Page Templates'),
-            pages.length > 0 && records(pages.map(toRow), {fields}),
-            blocks.length > 0 && section('Block Templates'),
-            blocks.length > 0 && records(blocks.map(toRow), {fields}),
-            section('Usage'),
-            text(
-              [
-                `${run} template <id> [target-path]     Scaffold page or block`,
-                `${run} template <id> --skeleton        Layout reference`,
-                `${run} template --list --type block    List only blocks`,
-                `${run} template --list --package <pkg> List from one package`,
-                `${run} template --cdn                 CDN starter page, no build step`,
-              ].join('\n'),
-            ),
-          );
-          break;
-        }
+          case 'template.skeleton': {
+            const {
+              template: tName,
+              description,
+              components,
+              skeleton,
+            } = result.data;
+            emit(
+              record({package: result.package}),
+              text(
+                `# ${tName}${description ? ' — ' + description : ''}\n` +
+                  `# Components: ${components.join(', ')}`,
+              ),
+              code(skeleton),
+            );
+            break;
+          }
 
-        case 'template.skeleton': {
-          const {template: tName, description, components, skeleton} = result.data;
-          emit(
-            record({package: result.package}),
-            text(
-              `# ${tName}${description ? ' — ' + description : ''}\n` +
-                `# Components: ${components.join(', ')}`,
-            ),
-            code(skeleton),
-          );
-          break;
-        }
+          case 'template.show': {
+            // Source must survive piping byte-for-byte, so the package it comes
+            // from (cli-surface INV28) and the note about replaced demo media go
+            // to stderr, the note in the copy receipt's words. (Text mode only:
+            // --json returned above with both in the envelope.)
+            const {source, demoMediaReplaced, demoContentReplaced, icons} =
+              result.data;
+            console.error(`package: ${result.package}`);
+            emit(code(source));
+            if (demoMediaReplaced > 0) {
+              console.error(
+                `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'}: ` +
+                  'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+              );
+            }
+            if (demoContentReplaced > 0) {
+              console.error(demoContentNote(demoContentReplaced));
+            }
+            // The icon report goes to stderr too, so stdout stays the source.
+            for (const line of iconLines(icons)) console.error(line);
+            break;
+          }
 
-        case 'template.show': {
-          // Source must survive piping byte-for-byte, so the package it comes
-          // from (cli-surface INV28) and the note about replaced demo media go
-          // to stderr, the note in the copy receipt's words. (Text mode only:
-          // --json returned above with both in the envelope.)
-          const {source, demoMediaReplaced, demoContentReplaced, icons} =
-            result.data;
-          console.error(`package: ${result.package}`);
-          emit(code(source));
-          if (demoMediaReplaced > 0) {
-            console.error(
-              `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'}: ` +
-                'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+          case 'template.copy': {
+            const {
+              outputDir,
+              fileName,
+              demoMediaReplaced,
+              demoContentReplaced,
+              notes,
+              icons,
+            } = result.data;
+            const file = `${outputDir}/${fileName}`;
+            const iconText = iconLines(icons);
+            emit(
+              text(`Copied template to ${file}`),
+              record({package: result.package}),
+              demoMediaReplaced > 0 &&
+                text(
+                  `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'} in ${file}: ` +
+                    'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+                ),
+              demoContentReplaced > 0 &&
+                text(demoContentNote(demoContentReplaced, file)),
+              ...notes.map(/** @param {string} note */ note => text(note)),
+              iconText.length > 0 && text(iconText.join('\n')),
             );
+            break;
           }
-          if (demoContentReplaced > 0) {
-            console.error(demoContentNote(demoContentReplaced));
-          }
-          // The icon report goes to stderr too, so stdout stays the source.
-          for (const line of iconLines(icons)) console.error(line);
-          break;
-        }
 
-        case 'template.copy': {
-          const {
-            outputDir,
-            fileName,
-            demoMediaReplaced,
-            demoContentReplaced,
-            notes,
-            icons,
-          } = result.data;
-          const file = `${outputDir}/${fileName}`;
-          const iconText = iconLines(icons);
-          emit(
-            text(`Copied template to ${file}`),
-            record({package: result.package}),
-            demoMediaReplaced > 0 &&
+          case 'template.cdn': {
+            if (!result.data.written) {
+              emit(
+                text(`[skip] ${result.data.path} already exists — left as is.`),
+                text('Pass --overwrite to replace it with a fresh copy.'),
+              );
+              break;
+            }
+            emit(
+              text(`[ok] Wrote ${result.data.path}`),
               text(
-                `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'} in ${file}: ` +
-                  'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+                `Open it in a browser — no bundler, no install, no build step. Every CDN URL is pinned to ${result.data.version}, and the annotations mark the parts that are load-bearing.`,
               ),
-            demoContentReplaced > 0 &&
-              text(demoContentNote(demoContentReplaced, file)),
-            ...notes.map(/** @param {string} note */ note => text(note)),
-            iconText.length > 0 && text(iconText.join('\n')),
-          );
-          break;
-        }
-
-        case 'template.cdn': {
-          if (!result.data.written) {
-            emit(
-              text(`[skip] ${result.data.path} already exists — left as is.`),
-              text('Pass --overwrite to replace it with a fresh copy.'),
             );
             break;
           }
-          emit(
-            text(`[ok] Wrote ${result.data.path}`),
-            text(
-              `Open it in a browser — no bundler, no install, no build step. Every CDN URL is pinned to ${result.data.version}, and the annotations mark the parts that are load-bearing.`,
-            ),
-          );
-          break;
         }
-      }
-      return answered;
-    },
+        return answered;
+      },
   });
 }

package/foundation/discovery/component-discovery.mjs

@@ -41,7 +41,7 @@ export const CORE_PACKAGE = CORE_PROVIDER_ID;
 const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
 
 // Component source files are named `XDS{Name}.tsx` today. The XDS-prefix
-// migration (P2380608025, P4) renames them to the bare `{Name}.tsx` form, so
+// migration (phase 4) renames them to the bare `{Name}.tsx` form, so
 // discovery must recognize BOTH. The `XDS` prefix has historically doubled as
 // a "this is a top-level component" marker, so naively matching all PascalCase
 // `.tsx` files would surface internal helpers that happen to be PascalCase

package/foundation/discovery/icon-set-writer.d.mts

@@ -11,7 +11,10 @@
 export function iconIdOf(name: string): string;
 /**
  * The name an icon set exports an icon as: PascalCase ending in `Icon`
- * (`Trash2` → `Trash2Icon`; `TrashIcon` stays).
+ * (`Trash2` → `Trash2Icon`; `TrashIcon` stays). A JavaScript name cannot
+ * start with a digit, so a name that starts with one is refused.
+ * {@link iconNaming} keeps a library prefix to prevent this (`fa0` →
+ * `Fa0Icon`).
  * @param {string} name
  */
 export function iconExportName(name: string): string;
@@ -27,7 +30,11 @@ export function variantExportName(iconName: string, variant: string): string;
  * `selector` names, else the only set.
  * @param {string} cwd
  * @param {string} [selector] a set name
- * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[]}>}
+ * The set's `module` names the package as package.json names it now;
+ * `moduleRenamed` says the data file still names an old name, so a command
+ * writes the data file even when nothing else changes; `moduleUpdate` gives
+ * the old and the new name for the receipt, else null.
+ * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[], moduleRenamed: boolean, moduleUpdate: {previous: string, module: string} | null}>}
  */
 export function findLocalIconSet(cwd: string, selector?: string): Promise<{
     packageDir: string;
@@ -35,6 +42,11 @@ export function findLocalIconSet(cwd: string, selector?: string): Promise<{
     root: string;
     set: DiscoveredIconSet;
     sets: DiscoveredIconSet[];
+    moduleRenamed: boolean;
+    moduleUpdate: {
+        previous: string;
+        module: string;
+    } | null;
 }>;
 /**
  * A data file's text, in one fixed shape: fields in schema order, `map` keys
@@ -147,7 +159,9 @@ export function nonIconExports(file: string, options?: {
 export function libraryPrefix(names: string[]): string[];
 /**
  * An export's id and the name the set exports it as, with the library prefix
- * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`.
+ * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`. A
+ * name that would start with a digit keeps the prefix (`fa500px` is
+ * `fa-500px`, `Fa500pxIcon`).
  * @param {string} name
  * @param {string[]} prefix
  * @returns {{id: string, name: string}}
@@ -371,7 +385,7 @@ export function writeDefinitionFile(set: DiscoveredIconSet, doc: {
 /**
  * Whether a generated declaration file declares what its generated module
  * gives, statement by statement however a formatter left either file
- * ({@link generatedStatements}); the header comment is ignored.
+ * ({@link statementTrees}); the header comment is ignored.
  * @param {string} actual the declaration file as it is
  * @param {string} expected {@link generatedTypesText} for the module
  * @param {string} label the declaration file's path, for a parse error
@@ -442,11 +456,13 @@ export function generatedNamesOf(packageDir: string, generated: string, from: st
  * differently; and a refresh changes only the icons its module supplies.
  * @param {string} packageDir
  * @param {string} generated
- * @returns {Map<string, {module: string, source: string}>}
+ * @returns {Map<string, {module: string, source: string, adapt: boolean}>}
+ *   `adapt`: the set's adapter turns the export into a component
  */
 export function generatedOrigins(packageDir: string, generated: string): Map<string, {
     module: string;
     source: string;
+    adapt: boolean;
 }>;
 /**
  * Whether two module specifiers name the same module: the same package