@astryxdesign/cli 0.3.0-canary.d1b7d82 → 0.3.0-canary.dccdabe

package/README.md

@@ -72,7 +72,7 @@ Options:
 | `search`               | Search components, hooks, docs, and templates in one ranked list              |
 | `swizzle`              | Copy component source for customization                                       |
 | `template`             | Inject a page or block template                                               |
-| `theme`                | Theme tools — build, export, and manage themes                                |
+| `theme`                | Theme tools: build, export, and manage themes                                 |
 | `upgrade`              | Run codemods to migrate between versions                                      |
 | `validate-integration` | Validate an Astryx integration package (manifest + contributions)             |
 
@@ -385,7 +385,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 | Type                        | What `data` carries                                                                                                                                                                                                                  |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `component.list`            | The component catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                      |
+| `component.list`            | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                       |
 | `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                    |
 | `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                               |
 | `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                 |
@@ -393,12 +393,12 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                           |
 | `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                              |
 | `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                        |
-| `docs.detail.section`       | A single ReferenceSection of a topic — the first whose title contains the section query.                                                                                                                                             |
-| `blog.list`                 | The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                            |
+| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                              |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                             |
 | `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                            |
 | `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                   |
 | `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                           |
-| `discover.detail.doc`       | The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                      |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                       |
 | `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                     |
 | `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                    |
 | `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                         |
@@ -409,15 +409,15 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                  |
 | `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                         |
 | `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                |
-| `hook.list`                 | The hook catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                   |
+| `hook.list`                 | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                    |
 | `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                    |
 | `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                   |
 | `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                    |
 | `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
-| `theme.list`                | Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.                                                                                                                         |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                          |
 | `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
 | `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
-| `upgrade.status`            | A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.                                                                                                    |
+| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                     |
 | `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |
 | `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.        |
 | `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                          |

package/api/blog/blog.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:
-    'Reads the design system blog the same way any feed reader does — over the ' +
+    'Reads the design system blog the same way any feed reader does, over the ' +
     "published RSS feed, never the blog's source files. With no slug it lists every " +
     "post parsed from the feed; with a slug it reads that post's full plaintext body " +
     'via the .txt alternate the feed advertises. Both envelopes carry feedUrl so a ' +
@@ -35,7 +35,7 @@ export const doc = {
     {
       type: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the feed — each with slug, title, description, date, type, authors, link, and its plaintext URL.',
+        'The feed URL plus every post parsed from the feed, each with slug, title, description, date, type, authors, link, and its plaintext URL.',
     },
     {
       type: 'blog.detail',

package/api/build/build.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted — a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
     },
     {
       type: 'build.kit',

package/api/component/component.doc.mjs

@@ -108,7 +108,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — names+package, brief entries, or full ComponentDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names+package, brief entries, or full ComponentDoc per entry.",
     },
     {
       type: 'component.detail',

package/api/discover/discover.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   summary: 'Browse and search components from configured external packages.',
   description:
     'Explores components contributed by configured external packages and integrations ' +
-    '— the ones that declare a components root. With no query it lists those packages; ' +
+    'the ones that declare a components root. With no query it lists those packages; ' +
     'an @scope/name query browses one package; @scope/name/Component (or a free-text ' +
     "term that resolves to a single component) returns that component's validated doc; " +
     'a free-text term with several matches returns the candidate list.',
@@ -68,7 +68,7 @@ export const doc = {
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
     },
     {
       type: 'discover.search',

package/api/docs/docs.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs — list every topic, one topic, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
   description:
     'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
@@ -75,7 +75,7 @@ export const doc = {
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic — the first whose title contains the section query.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [

package/api/doctor/doctor.doc.mjs

@@ -14,10 +14,10 @@ export const doc = {
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:
-    'Runs a series of side-effect-free diagnostics — Node version, ' +
+    'Runs a series of side-effect-free diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, agent docs, core peer ' +
-    'dependencies, and the detected package manager — and returns a structured ' +
+    'dependencies, and the detected package manager, and returns a structured ' +
     'report. It only reads (never installs, writes, or mutates), so it is safe ' +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks` — each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass` — plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
     },
   ],
   examples: [

package/api/hook/hook.doc.mjs

@@ -70,7 +70,7 @@ export const doc = {
     {
       type: 'hook.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — hook names, brief entries, or full HookDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: hook names, brief entries, or full HookDoc per entry.",
     },
     {
       type: 'hook.detail',

package/api/init/init.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when `removeAgents` is set.',
+        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
     },
   ],
   throws: [

package/api/integration/summarizeIssues.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Tally integration issues by severity into error and warning counts.',
   description:
     'A synchronous helper that reduces an AstryxIntegrationIssue[] (as returned ' +
-    'by validateIntegration) to counts of errors and warnings — the seam a ' +
+    'by validateIntegration) to counts of errors and warnings: the seam a ' +
     'caller uses to decide an exit code or print a summary line. Issues of any ' +
     'other severity are ignored.',
   importPath: '@astryxdesign/cli/api',

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues` — an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/assertResponse.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
     {
@@ -42,7 +42,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped — cast to the matching *Response type for typed access.',
+        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped; cast to the matching *Response type for typed access.',
     },
   ],
   throws: [

package/api/json/isError.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data` — ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/json/parseResponse.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
   ],
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped — narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/layoutCheck.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
     'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
     '(compact and outline). Validation failures are reported in the layout.check envelope ' +
-    '(valid: false) with line/col and suggestions — not thrown — so callers can lint an ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
     'expression and surface fixes.',
   importPath: '@astryxdesign/cli/api',
   signature:

package/api/layout/layoutExpand.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:
     'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
-    'expression, then expands it into ready-to-use XDS TSX — auto-routing structural children ' +
+    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
     'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
     'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
     'envelope, optionally writing it to a path within cwd.',

package/api/layout/layoutGrammar.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:
-    'The reference behind `astryx layout grammar` — the agent cheatsheet for writing XLE/XLO ' +
+    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
     "layout expressions, with the alias table generated from this branch's registry rather than " +
     'hand-maintained, so short names always reflect the components actually installed.',
   importPath: '@astryxdesign/cli/api',

package/api/swizzle/swizzle.doc.mjs

@@ -88,7 +88,7 @@ export const doc = {
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
-      when: 'more than one package provides the component — choose one with package',
+      when: 'more than one package provides the component; choose one with package',
     },
     {
       code: 'ERR_NO_SOURCE',

package/api/template/template.test.mjs

@@ -4,36 +4,35 @@ import {describe, it, expect} from 'vitest';
 import {stripTemplateAssetRefs, template} from './template.mjs';
 
 describe('stripTemplateAssetRefs', () => {
-  it('replaces a lookaside astryx image URL with an inline data URI', () => {
+  it('replaces a /template-assets image path with an inline data URI', () => {
     const src =
-      "const hero = 'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png';";
+      "const hero = '/template-assets/colorful-home-horizontal-1.png';";
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces a lookaside block-avatar image URL', () => {
-    const src =
-      'src="https://lookaside.facebook.com/assets/astryx/avatar-profile-05.jpg"';
+  it('replaces a /template-assets block-avatar image path', () => {
+    const src = 'src="/template-assets/avatar-profile-05.jpg"';
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces every lookaside reference, not just the first', () => {
+  it('replaces every /template-assets reference, not just the first', () => {
     const src = [
-      "'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png'",
-      "'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-3.png'",
-      "'https://lookaside.facebook.com/assets/astryx/moody-scene-horizontal-1.png'",
+      "'/template-assets/colorful-home-horizontal-1.png'",
+      "'/template-assets/illustrative-horizontal-3.png'",
+      "'/template-assets/moody-scene-horizontal-1.png'",
     ].join('\n');
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out.match(/data:image\/svg\+xml,/g)).toHaveLength(3);
   });
 
   it('preserves surrounding source structure', () => {
     const src =
-      "const data = [{src: 'https://lookaside.facebook.com/assets/astryx/x.png', alt: 'X'}];";
+      "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
     const out = stripTemplateAssetRefs(src);
     expect(out).toContain("alt: 'X'");
     expect(out).toContain('const data = [{src:');

package/api/theme/listThemes.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   displayName: 'listThemes()',
   summary: 'Read the bundled-theme manifest and return its raw entries.',
   description:
-    "The shared data layer behind theme list/add — reads the CLI's bundled-theme manifest " +
+    "The shared data layer behind theme list/add: reads the CLI's bundled-theme manifest " +
     '(templates/themes/manifest.json, generated by scripts/generate-cli-themes.mjs) and returns ' +
     'the parsed entries. themeList() projects this into the theme.list envelope; themeAdd() ' +
     'resolves a slug against it. Returns synchronously.',
@@ -28,7 +28,7 @@ export const doc = {
     {
       type: 'BundledTheme[]',
       description:
-        'The parsed themes array from the bundle manifest — each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
+        'The parsed themes array from the bundle manifest: each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
     },
   ],
   throws: [

package/api/theme/themeAdd.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Scaffold a bundled theme into a project as editable source.',
   description:
     "Copies a bundled theme's source (from the CLI's templates/themes/<slug>) into the " +
-    "consumer's project so they own it — no theme package needed. Writes are staged to temp " +
+    "consumer's project so they own it, no theme package needed. Writes are staged to temp " +
     'files then renamed, rolling back partials on failure so a failed write never leaves a ' +
     'half-written theme. Returns a theme.add receipt describing where the files landed and how ' +
     'to import them.',

package/api/theme/themeBuild.doc.mjs

@@ -20,7 +20,7 @@ export const doc = {
     'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
     'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
     'theme adds custom prop values). With {check: true} it writes nothing and instead compares ' +
-    'each output against disk, returning the drift — the CI guard for committed, generated theme CSS.',
+    'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeBuild(file: string, options?: {out?: string, check?: boolean}, ctx?: {cwd?: string}): Promise<ThemeBuildResponse | ThemeBuildCheckResponse | null>',
@@ -51,7 +51,7 @@ export const doc = {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing — the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
       default: 'false',
     },
     {
@@ -86,7 +86,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core/theme cannot be imported — a built, resolvable @astryxdesign/core is required',
+      when: '@astryxdesign/core/theme cannot be imported; a built, resolvable @astryxdesign/core is required',
     },
     {
       code: 'ERR_WRITE_FAILED',

package/api/theme/themeList.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List the themes bundled with this CLI build.',
   description:
-    'Projects the bundled-theme manifest into the theme.list envelope — the themes that themeAdd ' +
+    'Projects the bundled-theme manifest into the theme.list envelope: the themes that themeAdd ' +
     'can scaffold. A pure projection of the manifest read by listThemes(); no I/O beyond that read, ' +
     'and it returns synchronously.',
   importPath: '@astryxdesign/cli/api',
@@ -26,7 +26,7 @@ export const doc = {
     {
       type: 'theme.list',
       description:
-        'Every bundled theme as a ThemeListEntry[] — each entry has slug, displayName, description, and a maintained flag.',
+        'Every bundled theme as a ThemeListEntry[]: each entry has slug, displayName, description, and a maintained flag.',
     },
   ],
   throws: [

package/api/upgrade/upgrade.doc.mjs

@@ -86,7 +86,7 @@ export const doc = {
     {
       type: 'upgrade.list',
       description:
-        'Every available codemod, oldest→newest, as {name, title, version, optional} — returned when `list` is set; nothing is run.',
+        'Every available codemod, oldest→newest, as {name, title, version, optional}, returned when `list` is set; nothing is run.',
     },
     {
       type: 'upgrade.status',

package/assets/codemods/transforms/v0.3.0/__tests__/migrate-grid-minchildwidth-to-columns.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../migrate-grid-minchildwidth-to-columns.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+/** Collapse whitespace (and space padding inside braces) so formatting of
+ * pretty-printed multiline objects does not matter for assertions. */
+function normalize(str) {
+  return str
+    .replace(/\s+/g, ' ')
+    .replace(/\{\s+/g, '{')
+    .replace(/\s+\}/g, '}')
+    .trim();
+}
+
+describe('migrate-grid-minchildwidth-to-columns', () => {
+  it('migrates minChildWidth only to columns={{minWidth, repeat: "fit"}}', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 280, repeat: 'fit'}}"),
+    );
+  });
+
+  it('migrates columns={n} + minChildWidth to columns={{minWidth, max, repeat: "fit"}}', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={3} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 280, max: 3, repeat: 'fit'}}"),
+    );
+  });
+
+  it('preserves other attributes (gap) when migrating the combo', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={5} gap={5} minChildWidth={140}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 140, max: 5, repeat: 'fit'}}"),
+    );
+    expect(output).toContain('gap={5}');
+  });
+
+  it('bails when columns is already an object (ambiguous)', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={{minWidth: 100}} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    // Unchanged: object columns is ambiguous, so it is left as-is.
+    expect(output).toBe(input);
+  });
+
+  it('bails when columns is a non-numeric/dynamic expression', async () => {
+    const input = `import {Grid} from '@astryxdesign/core';
+const t = <Grid columns={cols} minChildWidth={280}><Item /></Grid>;`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('is alias-aware and supports the subpath import source', async () => {
+    const input = `import {Grid as G} from '@astryxdesign/core/Grid';
+const t = <G columns={4} minChildWidth={200}><Item /></G>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('minChildWidth');
+    expect(normalize(output)).toContain(
+      normalize("columns={{minWidth: 200, max: 4, repeat: 'fit'}}"),
+    );
+  });
+});

package/assets/codemods/transforms/v0.3.0/migrate-grid-minchildwidth-to-columns.mjs

@@ -49,11 +49,10 @@ export default function transformer(file, api) {
         a.type === 'JSXAttribute' && a.name?.name === 'minChildWidth',
     );
     if (!minAttr) return;
-    const hasColumns = attrs.some(
+    const columnsAttr = attrs.find(
       (/** @type {any} */ a) =>
         a.type === 'JSXAttribute' && a.name?.name === 'columns',
     );
-    if (hasColumns) return;
 
     let minWidthExpr;
     if (
@@ -67,6 +66,43 @@ export default function transformer(file, api) {
       return;
     }
 
+    if (columnsAttr) {
+      // Both `columns` and `minChildWidth` are present. This is only safely
+      // migratable when `columns` is a numeric literal (e.g. `columns={3}`).
+      //
+      // In the old (0.2.0) Grid runtime, when both props were set and
+      // `columns` was a number, `minChildWidth` dominated and the numeric
+      // `columns` became a *max column cap* with `auto-fit`:
+      //   repeat(auto-fit, minmax(minChildWidth, 1fr)) capped at `columns`.
+      // The 0.3.0 `columns` object models this exactly as
+      //   {minWidth, max, repeat: 'fit'}.
+      // So the lossless rewrite is:
+      //   <Grid columns={3} minChildWidth={280}>
+      //     -> <Grid columns={{minWidth: 280, max: 3, repeat: 'fit'}}>
+      //
+      // If `columns` is already an object or a non-numeric/dynamic
+      // expression, the combined behavior is genuinely ambiguous, so we
+      // bail and leave it unmigrated (it surfaces separately).
+      const columnsValue = columnsAttr.value;
+      if (columnsValue?.type !== 'JSXExpressionContainer') return;
+      const columnsExpr = columnsValue.expression;
+      const isNumericLiteral =
+        (columnsExpr?.type === 'NumericLiteral' ||
+          columnsExpr?.type === 'Literal') &&
+        typeof columnsExpr.value === 'number';
+      if (!isNumericLiteral) return;
+
+      const columnsObject = j.objectExpression([
+        j.property('init', j.identifier('minWidth'), minWidthExpr),
+        j.property('init', j.identifier('max'), j.literal(columnsExpr.value)),
+        j.property('init', j.identifier('repeat'), j.literal('fit')),
+      ]);
+      columnsAttr.value = j.jsxExpressionContainer(columnsObject);
+      attrs.splice(attrs.indexOf(minAttr), 1);
+      hasChanges = true;
+      return;
+    }
+
     const columnsObject = j.objectExpression([
       j.property('init', j.identifier('minWidth'), minWidthExpr),
       j.property('init', j.identifier('repeat'), j.literal('fit')),