@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.db4e378

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/README.md +86 -72
  2. package/api/build/build.doc.mjs +3 -3
  3. package/api/build/build.test.mjs +14 -3
  4. package/api/build/build.type.d.mts +35 -1
  5. package/api/build/build.type.mjs +24 -3
  6. package/api/build/help/help.d.mts +8 -5
  7. package/api/build/help/help.mjs +56 -6
  8. package/api/component/component.doc.mjs +12 -3
  9. package/api/component/component.mjs +31 -2
  10. package/api/component/component.test.mjs +38 -0
  11. package/api/component/component.type.d.mts +16 -5
  12. package/api/component/component.type.mjs +13 -5
  13. package/api/component/detail/blocks/blocks.d.mts +2 -1
  14. package/api/component/detail/blocks/blocks.mjs +4 -3
  15. package/api/component/list/list.d.mts +0 -5
  16. package/api/component/list/list.mjs +37 -9
  17. package/api/discover/discover.doc.mjs +1 -1
  18. package/api/gap-report/gap-report.doc.mjs +7 -4
  19. package/api/init/init.doc.mjs +4 -0
  20. package/api/init/init.test.mjs +41 -1
  21. package/api/init/remove/remove.mjs +1 -1
  22. package/api/init/run/run.mjs +20 -10
  23. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  24. package/api/integration/add-contribution.mjs +11 -0
  25. package/api/integration/add-contribution.test.mjs +80 -0
  26. package/api/integration/integrationAdd.doc.mjs +7 -4
  27. package/api/integration/integrationAddComponent.doc.mjs +1 -1
  28. package/api/integration/validate-integration.mjs +2 -0
  29. package/api/integration/validate-integration.test.mjs +91 -0
  30. package/api/integration/validateIntegration.doc.mjs +1 -1
  31. package/api/json/envelope-types.test.mjs +76 -0
  32. package/api/json/parseResponse.doc.mjs +2 -2
  33. package/api/layout/expand/expand.mjs +7 -5
  34. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  35. package/api/layout/grammar/grammar.mjs +2 -1
  36. package/api/layout/layoutExpand.doc.mjs +1 -1
  37. package/api/search/search-return-type.test.mjs +54 -0
  38. package/api/search/search.d.mts +2 -9
  39. package/api/search/search.doc.mjs +5 -1
  40. package/api/search/search.mjs +10 -3
  41. package/api/search/search.test.mjs +34 -0
  42. package/api/swizzle/copy/copy.mjs +28 -11
  43. package/api/swizzle/swizzle.doc.mjs +1 -1
  44. package/api/template/copy/copy.mjs +17 -23
  45. package/api/template/copy/copy.test.mjs +17 -0
  46. package/api/template/template.doc.mjs +2 -1
  47. package/api/theme/add/add.binary.test.mjs +91 -0
  48. package/api/theme/add/add.mjs +20 -3
  49. package/api/theme/add/add.staging.test.mjs +66 -0
  50. package/api/theme/build/build.mjs +114 -37
  51. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  52. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  53. package/api/theme/build/font-warning.mjs +3 -3
  54. package/api/theme/build/font-warning.test.mjs +5 -2
  55. package/api/theme/palette/generate/generate.mjs +7 -2
  56. package/api/theme/palette/generate/generate.test.mjs +96 -0
  57. package/api/theme/palette/generate/generator.mjs +8 -1
  58. package/api/theme/palette/generate/generator.test.mjs +10 -0
  59. package/api/theme/template/template.mjs +11 -2
  60. package/api/theme/template/template.test.mjs +15 -0
  61. package/api/theme/themeBuild.doc.mjs +7 -4
  62. package/api/theme/themeTemplate.doc.mjs +4 -1
  63. package/api/upgrade/_adapter.mjs +27 -4
  64. package/api/upgrade/list/list.mjs +2 -1
  65. package/api/upgrade/list/list.test.mjs +73 -0
  66. package/api/upgrade/status/status.mjs +2 -2
  67. package/api/upgrade/upgrade.doc.mjs +2 -1
  68. package/api/upgrade/upgrade.type.d.mts +4 -0
  69. package/api/upgrade/upgrade.type.mjs +1 -0
  70. package/assets/codemods/term-log.mjs +32 -8
  71. package/assets/codemods/term-log.test.mjs +19 -1
  72. package/assets/codemods/transform-prop.mjs +109 -0
  73. package/assets/codemods/transform-prop.test.mjs +95 -0
  74. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  75. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  76. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  77. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  78. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  79. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  80. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  81. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  82. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  83. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  84. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  85. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  86. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  87. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  88. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  89. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  90. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  91. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  92. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  93. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  94. package/authoring/config/config.doc.mjs +1 -1
  95. package/authoring/config/debug-composition.test.mjs +92 -0
  96. package/authoring/config/type.ts +15 -3
  97. package/clients/cli/command-load-failure.test.mjs +83 -0
  98. package/clients/cli/commands/blog.mjs +23 -8
  99. package/clients/cli/commands/blog.test.mjs +42 -1
  100. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  101. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  102. package/clients/cli/commands/build-theme.mjs +5 -5
  103. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  104. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  105. package/clients/cli/commands/build.doc.mjs +4 -1
  106. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  107. package/clients/cli/commands/build.mjs +32 -47
  108. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  109. package/clients/cli/commands/build.text-fields.test.mjs +40 -0
  110. package/clients/cli/commands/component/index.mjs +2 -7
  111. package/clients/cli/commands/component-package.test.mjs +46 -0
  112. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  113. package/clients/cli/commands/component.test.mjs +19 -0
  114. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  115. package/clients/cli/commands/discover.broken-integration.test.mjs +48 -0
  116. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  117. package/clients/cli/commands/discover.doc.mjs +4 -2
  118. package/clients/cli/commands/discover.mjs +3 -3
  119. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  120. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  121. package/clients/cli/commands/doctor.mjs +6 -16
  122. package/clients/cli/commands/doctor.test.mjs +42 -0
  123. package/clients/cli/commands/gap-report.doc.mjs +16 -5
  124. package/clients/cli/commands/gap-report.test.mjs +72 -0
  125. package/clients/cli/commands/hook/index.mjs +7 -17
  126. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  127. package/clients/cli/commands/init.doc.mjs +19 -8
  128. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  129. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  130. package/clients/cli/commands/integration-add.doc.mjs +21 -5
  131. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  132. package/clients/cli/commands/json-contract.test.mjs +33 -0
  133. package/clients/cli/commands/layout-check.doc.mjs +14 -3
  134. package/clients/cli/commands/layout-expand.doc.mjs +21 -4
  135. package/clients/cli/commands/layout.doc.mjs +2 -2
  136. package/clients/cli/commands/layout.mjs +21 -9
  137. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  138. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  139. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  140. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  141. package/clients/cli/commands/search.doc.mjs +6 -3
  142. package/clients/cli/commands/search.mjs +17 -7
  143. package/clients/cli/commands/search.test.mjs +75 -0
  144. package/clients/cli/commands/swizzle.doc.mjs +2 -1
  145. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  146. package/clients/cli/commands/template.doc.mjs +28 -6
  147. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  148. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  149. package/clients/cli/commands/theme-add.doc.mjs +2 -1
  150. package/clients/cli/commands/theme-build.doc.mjs +7 -6
  151. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  152. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  153. package/clients/cli/commands/theme-template.doc.mjs +1 -1
  154. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  155. package/clients/cli/commands/upgrade.doc.mjs +17 -6
  156. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  157. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  158. package/clients/cli/index.mjs +13 -30
  159. package/clients/cli/latest-version-env.test.mjs +50 -0
  160. package/clients/cli/lib/cli-error.test.mjs +7 -0
  161. package/clients/cli/lib/component-format.mjs +9 -9
  162. package/clients/cli/lib/component-format.test.mjs +1 -1
  163. package/clients/cli/lib/define-command.mjs +32 -6
  164. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  165. package/clients/cli/lib/exit-codes.test.mjs +97 -0
  166. package/clients/cli/lib/hook-format.mjs +5 -5
  167. package/clients/cli/lib/json-shim.mjs +38 -2
  168. package/clients/cli/lib/json-shim.test.mjs +83 -0
  169. package/clients/cli/lib/manifest.d.ts +2 -0
  170. package/clients/cli/lib/manifest.mjs +22 -0
  171. package/clients/cli/lib/manifest.test.mjs +17 -0
  172. package/foundation/agent-docs/agent-docs.d.mts +4 -0
  173. package/foundation/agent-docs/agent-docs.mjs +69 -3
  174. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  175. package/foundation/config/integration-debug.test.mjs +28 -3
  176. package/foundation/config/project.mjs +123 -9
  177. package/foundation/config/project.test.mjs +126 -0
  178. package/foundation/discovery/template-adapter.d.mts +14 -5
  179. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  180. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  181. package/foundation/discovery/template-adapter.mjs +292 -25
  182. package/foundation/discovery/theming-targets.test.mjs +4 -0
  183. package/foundation/fs/module-loader.d.mts +1 -0
  184. package/foundation/fs/module-loader.mjs +50 -1
  185. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  186. package/foundation/fs/path-safety.d.mts +3 -2
  187. package/foundation/fs/path-safety.mjs +49 -19
  188. package/foundation/fs/path-safety.test.mjs +50 -0
  189. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  190. package/foundation/integrations/autolink.mjs +6 -1
  191. package/foundation/response/base.d.ts +8 -4
  192. package/foundation/response/error-codes.doc.mjs +1 -2
  193. package/foundation/response/error-codes.mjs +1 -1
  194. package/foundation/response/error-codes.test.mjs +83 -0
  195. package/foundation/response/json-contract.test.mjs +11 -0
  196. package/foundation/response/json.d.mts +4 -2
  197. package/foundation/response/json.mjs +8 -10
  198. package/foundation/response/response-types.doc.mjs +10 -10
  199. package/foundation/response/response-types.doc.test.mjs +158 -0
  200. package/foundation/xle/expand.d.mts +2 -0
  201. package/foundation/xle/expand.mjs +3 -2
  202. package/foundation/xle/expand.test.mjs +54 -0
  203. package/package.json +9 -9
  204. package/clients/cli/lib/update-check.mjs +0 -83
  205. package/clients/cli/lib/update-check.test.mjs +0 -137
  206. package/clients/cli/update-hint-commands.test.mjs +0 -54
@@ -23,6 +23,7 @@
23
23
 
24
24
  import * as fs from 'node:fs';
25
25
  import * as path from 'node:path';
26
+ import {createRequire} from 'node:module';
26
27
  import {createJiti} from 'jiti';
27
28
  import {loadModuleWithParser} from '../fs/module-loader.mjs';
28
29
  import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
@@ -30,6 +31,8 @@ import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
30
31
  import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
31
32
  import {Project} from '../config/project.mjs';
32
33
 
34
+ const require = createRequire(import.meta.url);
35
+
33
36
  /** Identity used for core (built-in) templates in package-scoped listings. */
34
37
  const CORE_PACKAGE = CORE_PROVIDER_ID;
35
38
 
@@ -185,17 +188,53 @@ const IMAGE_EXTENSIONS = new Set([
185
188
  ]);
186
189
 
187
190
  /**
188
- * Demo-asset sources to strip from scaffolded projects. Template demo imagery
191
+ * First path segment of every Astryx template fixture. Template demo imagery
189
192
  * is self-hosted under the docsite's `/template-assets/*` dir (committed there,
190
- * mirrored into the sandbox preview by scripts/sync-templates.js). Those paths
191
- * only resolve inside the Astryx docsite/sandbox, so on scaffold they're
192
- * replaced — a scaffolded project has no `/template-assets/` dir and would
193
- * otherwise 404. Genuine third-party URLs (e.g. brand logos from
194
- * paypalobjects.com) are intentionally left untouched.
195
- *
196
- * @type {RegExp}
193
+ * mirrored into the sandbox preview by scripts/sync-templates.js), so those
194
+ * paths only resolve inside the Astryx docsite/sandbox and are replaced on
195
+ * scaffold. Only a root-relative URL whose first segment this is counts: the
196
+ * same text inside a third-party URL or a product path is left untouched.
197
197
  */
198
- const DEMO_ASSET_PATTERN = /\/template-assets\/[\w.-]+\.(\w+)/g;
198
+ const FIXTURE_SEGMENT = 'template-assets';
199
+
200
+ /** Characters that end a URL token in template source, besides whitespace. */
201
+ const TOKEN_DELIMITERS = new Set([
202
+ "'",
203
+ '"',
204
+ '`',
205
+ '(',
206
+ ')',
207
+ '<',
208
+ '>',
209
+ '{',
210
+ '}',
211
+ '[',
212
+ ']',
213
+ '\\',
214
+ '|',
215
+ '^',
216
+ ]);
217
+
218
+ /** The closing delimiter each opening delimiter must pair with. */
219
+ const CLOSING_DELIMITERS = new Map([
220
+ ["'", "'"],
221
+ ['"', '"'],
222
+ ['`', '`'],
223
+ ['(', ')'],
224
+ ]);
225
+ const CLOSERS = new Set(CLOSING_DELIMITERS.values());
226
+
227
+ /** A URL with a scheme: absolute, so never a fixture reference. */
228
+ const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/iu;
229
+
230
+ /** What may lead up to the fixture segment inside a relative product path. */
231
+ const RELATIVE_PATH_PREFIX = /^[\w.~%@/-]+$/u;
232
+
233
+ /** Punctuation that ends a sentence or list item after a path in text. */
234
+ const PROSE_PUNCTUATION = new Set(['.', ',', ';', ':', '!', '?']);
235
+
236
+ /** `from`, `import` or `require` right before a quoted module specifier. */
237
+ const MODULE_SPECIFIER_LEAD = /(?:^|[^\w$])(?:from|import|require)\s*\(?$/u;
199
238
 
200
239
  /**
201
240
  * Normalize path into Unix path (using forward slashes) for consistent comparison
@@ -209,26 +248,246 @@ function toPosixPath(p) {
209
248
  }
210
249
 
211
250
  /**
212
- * Replace demo asset references with a placeholder so scaffolded pages
213
- * render with zero setup. Images get a self-contained data URI; videos
214
- * (which have no equivalent inline placeholder — see VIDEO_EXTENSIONS) are
215
- * stripped to an empty src instead of being mis-replaced with image data.
216
- * Builders drop in their own media either way.
251
+ * Replace each Astryx template fixture reference with a placeholder so
252
+ * scaffolded pages render with zero setup. Images get a self-contained data
253
+ * URI; videos (which have no equivalent inline placeholder — see
254
+ * VIDEO_EXTENSIONS) are stripped to an empty src instead of being
255
+ * mis-replaced with image data. Builders drop in their own media either way.
256
+ *
257
+ * A reference is a URL token that resolves to a root-relative path under
258
+ * FIXTURE_SEGMENT. It is replaced whole, query and fragment included, and
259
+ * classified by the suffix of its last path segment. A reference that cannot
260
+ * be replaced safely throws with its path rather than being guessed at or
261
+ * left behind. Prose is left as written: in text (JSX text, a word inside a
262
+ * longer string) trailing punctuation is not part of a path and a path with
263
+ * no suffix, such as the bare directory, is a mention; inside a comment
264
+ * nothing throws.
217
265
  *
218
266
  * @param {string} source - Template source code.
219
267
  * @returns {string} Source with demo asset references replaced.
220
268
  */
221
269
  export function stripTemplateAssetRefs(source) {
222
- return source.replace(DEMO_ASSET_PATTERN, (match, extension) => {
223
- const ext = extension.toLowerCase();
224
- if (VIDEO_EXTENSIONS.has(ext)) {
225
- return '';
270
+ const needle = `/${FIXTURE_SEGMENT}`;
271
+ let output = '';
272
+ let copied = 0;
273
+ /** @type {Array<[number, number]> | undefined} */
274
+ let comments;
275
+ let at = source.indexOf(needle);
276
+ while (at !== -1) {
277
+ let start = at;
278
+ while (start > 0 && !isTokenDelimiter(source[start - 1])) start--;
279
+ let end = at + needle.length;
280
+ while (end < source.length && !isTokenDelimiter(source[end])) end++;
281
+ /** @type {{text: string, end: number} | null} */
282
+ let edit;
283
+ try {
284
+ edit = fixtureEdit(source, start, at, end);
285
+ } catch (err) {
286
+ comments ??= commentRanges(source);
287
+ if (!comments.some(([from, to]) => from <= at && at < to)) throw err;
288
+ edit = null;
226
289
  }
227
- if (IMAGE_EXTENSIONS.has(ext)) {
228
- return PLACEHOLDER_IMAGE;
290
+ if (edit) {
291
+ output += source.slice(copied, start) + edit.text;
292
+ copied = edit.end;
229
293
  }
230
- throw new Error(`Unrecognized template asset format ${ext} for ${match}`);
231
- });
294
+ at = source.indexOf(needle, end);
295
+ }
296
+ return output + source.slice(copied);
297
+ }
298
+
299
+ /** @param {string | undefined} char */
300
+ function isTokenDelimiter(char) {
301
+ return char === undefined || /\s/u.test(char) || TOKEN_DELIMITERS.has(char);
302
+ }
303
+
304
+ /**
305
+ * Whitespace, the source edge, or a tag bracket: what bounds a word of text.
306
+ * @param {string | undefined} char
307
+ */
308
+ function isTextDelimiter(char) {
309
+ return char === undefined || /\s/u.test(char) || char === '<' || char === '>';
310
+ }
311
+
312
+ /**
313
+ * The path segments of a root-relative URL under FIXTURE_SEGMENT, or null.
314
+ * @param {string} reference
315
+ * @returns {string[] | null}
316
+ */
317
+ function fixtureSegments(reference) {
318
+ if (!reference.startsWith('/') || reference.startsWith('//')) return null;
319
+ const segments = new URL(reference, 'http://template.invalid').pathname.split(
320
+ '/',
321
+ );
322
+ return segments[1] === FIXTURE_SEGMENT ? segments : null;
323
+ }
324
+
325
+ /**
326
+ * The replacement for the fixture reference in the URL token [start, end),
327
+ * which contains FIXTURE_SEGMENT's path at `at`; null when the token is not a
328
+ * fixture reference or is a prose mention.
329
+ * @param {string} source
330
+ * @param {number} start
331
+ * @param {number} at
332
+ * @param {number} end
333
+ * @returns {{text: string, end: number} | null}
334
+ */
335
+ function fixtureEdit(source, start, at, end) {
336
+ const token = source.slice(start, end);
337
+ if (ABSOLUTE_URL.test(token)) return null;
338
+ if (!token.startsWith('/')) {
339
+ if (!fixtureSegments(source.slice(at, end))) return null;
340
+ if (
341
+ source[start - 1] !== '\\' &&
342
+ RELATIVE_PATH_PREFIX.test(source.slice(start, at))
343
+ ) {
344
+ return null;
345
+ }
346
+ throw unsafeFixtureReference(
347
+ source,
348
+ at,
349
+ 'it is joined to text the copy cannot parse',
350
+ );
351
+ }
352
+
353
+ const before = source[start - 1];
354
+ const after = source[end];
355
+ if (after === '{' && token.endsWith('$')) {
356
+ if (!fixtureSegments(token.slice(0, -1))) return null;
357
+ throw unsafeFixtureReference(
358
+ source,
359
+ at,
360
+ 'it is built by a template-literal interpolation',
361
+ );
362
+ }
363
+ const quoted =
364
+ before !== undefined && CLOSING_DELIMITERS.get(before) === after;
365
+ const escapedQuoted =
366
+ (before === "'" || before === '"') &&
367
+ source[start - 2] === '\\' &&
368
+ after === '\\' &&
369
+ source[end + 1] === before;
370
+ const whole = quoted || escapedQuoted;
371
+ let referenceEnd = end;
372
+ if (!whole) {
373
+ while (
374
+ referenceEnd > at &&
375
+ PROSE_PUNCTUATION.has(source[referenceEnd - 1])
376
+ ) {
377
+ referenceEnd--;
378
+ }
379
+ }
380
+ const segments = fixtureSegments(source.slice(start, referenceEnd));
381
+ if (!segments) return null;
382
+
383
+ const inText =
384
+ (isTextDelimiter(before) || CLOSING_DELIMITERS.has(before)) &&
385
+ (isTextDelimiter(after) || CLOSERS.has(after)) &&
386
+ (isTextDelimiter(before) || isTextDelimiter(after));
387
+ if (!whole && !inText) {
388
+ throw unsafeFixtureReference(
389
+ source,
390
+ at,
391
+ 'it is not a whole quoted, url(), or text value',
392
+ );
393
+ }
394
+ if (quoted && before !== '(') {
395
+ const use = expressionUse(source, start - 1, end);
396
+ if (use) throw unsafeFixtureReference(source, at, use);
397
+ }
398
+
399
+ const ext = path.posix
400
+ .extname(segments[segments.length - 1])
401
+ .slice(1)
402
+ .toLowerCase();
403
+ if (VIDEO_EXTENSIONS.has(ext)) return {text: '', end: referenceEnd};
404
+ if (IMAGE_EXTENSIONS.has(ext)) {
405
+ return {text: PLACEHOLDER_IMAGE, end: referenceEnd};
406
+ }
407
+ if (whole || ext) {
408
+ throw new Error(
409
+ `Unrecognized template asset format ${ext || '(none)'} for ${displayReference(source, at)}`,
410
+ );
411
+ }
412
+ return null;
413
+ }
414
+
415
+ /**
416
+ * Why the string quoted at `open` and `close` cannot be replaced on its own,
417
+ * or null when it is a plain value.
418
+ * @param {string} source
419
+ * @param {number} open
420
+ * @param {number} close
421
+ * @returns {string | null}
422
+ */
423
+ function expressionUse(source, open, close) {
424
+ let prev = open - 1;
425
+ while (prev >= 0 && /\s/u.test(source[prev])) prev--;
426
+ let next = close + 1;
427
+ while (next < source.length && /\s/u.test(source[next])) next++;
428
+ if (
429
+ source[prev] === '+' ||
430
+ (source[prev] === '=' && source[prev - 1] === '+') ||
431
+ source[next] === '+'
432
+ ) {
433
+ return 'the string is concatenated with another value';
434
+ }
435
+ if (source[next] === '.' && /[A-Za-z_$]/u.test(source[next + 1] ?? '')) {
436
+ return 'a method is called on the string';
437
+ }
438
+ if (
439
+ MODULE_SPECIFIER_LEAD.test(source.slice(Math.max(0, prev - 16), prev + 1))
440
+ ) {
441
+ return 'it is imported as a module';
442
+ }
443
+ return null;
444
+ }
445
+
446
+ /**
447
+ * The [start, end) range of every comment in `source`, or none when it does
448
+ * not parse as TSX.
449
+ * @param {string} source
450
+ * @returns {Array<[number, number]>}
451
+ */
452
+ function commentRanges(source) {
453
+ try {
454
+ const {parse} = require('@babel/parser');
455
+ const {comments} = parse(source, {
456
+ sourceType: 'module',
457
+ plugins: ['jsx', 'typescript'],
458
+ });
459
+ return (comments ?? []).map(
460
+ comment =>
461
+ /** @type {[number, number]} */ ([
462
+ comment.start ?? 0,
463
+ comment.end ?? 0,
464
+ ]),
465
+ );
466
+ } catch {
467
+ return [];
468
+ }
469
+ }
470
+
471
+ /**
472
+ * The fixture path at `at`, up to the next whitespace, quote, or tag bracket.
473
+ * @param {string} source
474
+ * @param {number} at
475
+ */
476
+ function displayReference(source, at) {
477
+ let end = at;
478
+ while (end < source.length && !/[\s'"`<>]/u.test(source[end])) end++;
479
+ return source.slice(at, end);
480
+ }
481
+
482
+ /**
483
+ * @param {string} source
484
+ * @param {number} at
485
+ * @param {string} reason
486
+ */
487
+ function unsafeFixtureReference(source, at, reason) {
488
+ return new Error(
489
+ `Template asset reference ${displayReference(source, at)} cannot be replaced safely: ${reason}. Use the complete path as one static string.`,
490
+ );
232
491
  }
233
492
  /**
234
493
  * Load a template-spec module and return its metadata object. Supports both
@@ -545,9 +804,17 @@ async function discoverIntegrationTemplates(cwd = process.cwd()) {
545
804
  }
546
805
 
547
806
  for (const integration of loadedIntegrations) {
548
- const result = await discoverIntegrationTemplatesForOne(integration);
549
- templates.push(...result.templates);
550
- errors.push(...result.errors);
807
+ // One integration's unreadable root must not cost core or the others theirs.
808
+ try {
809
+ const result = await discoverIntegrationTemplatesForOne(integration);
810
+ templates.push(...result.templates);
811
+ errors.push(...result.errors);
812
+ } catch (err) {
813
+ errors.push({
814
+ package: integration?.name ?? integration?.__spec ?? 'integration',
815
+ message: err instanceof Error ? err.message : String(err),
816
+ });
817
+ }
551
818
  }
552
819
 
553
820
  return {templates, errors};
@@ -265,14 +265,18 @@ describe('collectThemingTargets', () => {
265
265
  expect(doc.subComponentOf).toBe('Dialog');
266
266
  expect(doc.theming.targets).toEqual([
267
267
  {className: 'astryx-dialog-header'},
268
+ {className: 'astryx-dialog-header-start-content'},
268
269
  {className: 'astryx-dialog-header-title-block'},
270
+ {className: 'astryx-dialog-header-end-content'},
269
271
  {className: 'astryx-dialog-header-close-icon'},
270
272
  ]);
271
273
  });
272
274
 
273
275
  it.each([
274
276
  'dialog-header',
277
+ 'dialog-header-start-content',
275
278
  'dialog-header-title-block',
279
+ 'dialog-header-end-content',
276
280
  'dialog-header-close-icon',
277
281
  ])('enumerates %s once under its canonical Dialog owner', async key => {
278
282
  const matches = (await enumerated).filter(target => target.key === key);
@@ -9,6 +9,7 @@
9
9
  * nearest package.json `type` decides `.js`, matching Node's package scopes.
10
10
  * Normal loads retain module caching. `fresh` is an explicit migration-only
11
11
  * escape hatch for rereading files that a codemod changed during this process.
12
+ * Anything the module writes to stdout while it loads goes to stderr.
12
13
  *
13
14
  * @param {string} file absolute path
14
15
  * @param {{fresh?: boolean}} [options]
@@ -7,7 +7,8 @@
7
7
  * user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
8
8
  * import) and (b) find conventional files by basename in a fixed
9
9
  * load-precedence order. These helpers centralize that so the two callers stay
10
- * in lockstep.
10
+ * in lockstep. A module's stdout writes go to stderr while it loads, so
11
+ * project code that prints cannot corrupt a `--json` envelope.
11
12
  *
12
13
  * `loadModuleWithParser` builds on these primitives to provide the single
13
14
  * load/validation boundary shared by config, integration, codemod, and
@@ -16,6 +17,7 @@
16
17
  */
17
18
 
18
19
  import * as path from 'node:path';
20
+ import {AsyncLocalStorage} from 'node:async_hooks';
19
21
  import {createRequire} from 'node:module';
20
22
  import {pathToFileURL} from 'node:url';
21
23
  import * as fs from 'node:fs';
@@ -56,6 +58,43 @@ function isCommonJsFile(file) {
56
58
  }
57
59
  }
58
60
 
61
+ let loadsInFlight = 0;
62
+ /** @type {typeof process.stdout.write | undefined} */
63
+ let realStdoutWrite;
64
+ /** Set in the async context of a module load, and only there. */
65
+ const moduleLoad = new AsyncLocalStorage();
66
+
67
+ /**
68
+ * Run a module load with the stdout writes made in its async context sent to
69
+ * stderr. Writes from any other context pass through, so the CLI's own output
70
+ * stays on stdout even while an abandoned load is still in flight. The gate
71
+ * is installed for the first overlapping load and removed after the last.
72
+ * @template T
73
+ * @param {() => Promise<T>} load
74
+ * @returns {Promise<T>}
75
+ */
76
+ async function withStdoutOnStderr(load) {
77
+ if (loadsInFlight++ === 0) {
78
+ const write = process.stdout.write;
79
+ realStdoutWrite = write;
80
+ process.stdout.write = /** @type {any} */ (
81
+ function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
82
+ return moduleLoad.getStore()
83
+ ? process.stderr.write(chunk, ...rest)
84
+ : write.call(process.stdout, chunk, ...rest);
85
+ }
86
+ );
87
+ }
88
+ try {
89
+ return await moduleLoad.run(true, load);
90
+ } finally {
91
+ if (--loadsInFlight === 0 && realStdoutWrite) {
92
+ process.stdout.write = realStdoutWrite;
93
+ realStdoutWrite = undefined;
94
+ }
95
+ }
96
+ }
97
+
59
98
  /**
60
99
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
61
100
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
@@ -64,12 +103,22 @@ function isCommonJsFile(file) {
64
103
  * nearest package.json `type` decides `.js`, matching Node's package scopes.
65
104
  * Normal loads retain module caching. `fresh` is an explicit migration-only
66
105
  * escape hatch for rereading files that a codemod changed during this process.
106
+ * Anything the module writes to stdout while it loads goes to stderr.
67
107
  *
68
108
  * @param {string} file absolute path
69
109
  * @param {{fresh?: boolean}} [options]
70
110
  * @returns {Promise<Record<string, unknown>>}
71
111
  */
72
112
  export async function importUserModule(file, {fresh = false} = {}) {
113
+ return await withStdoutOnStderr(() => importModule(file, fresh));
114
+ }
115
+
116
+ /**
117
+ * @param {string} file absolute path
118
+ * @param {boolean} fresh
119
+ * @returns {Promise<Record<string, unknown>>}
120
+ */
121
+ async function importModule(file, fresh) {
73
122
  if (fresh && file.endsWith('.ts')) {
74
123
  return await createJiti(import.meta.url, {moduleCache: false}).import(file);
75
124
  }