@astryxdesign/cli 0.1.6 → 0.1.7-canary.0a6de96

package/src/codemods/transforms/v0.1.7/__tests__/rename-table-renderprops-styles-to-xstyle.test.mjs

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import(
+    '../rename-table-renderprops-styles-to-xstyle.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;
+}
+
+describe('rename-table-renderprops-styles-to-xstyle', () => {
+  it('renames `props.styles` reads when the param is typed TableRenderProps', async () => {
+    const input = `function transformTable(props: TableRenderProps) {
+  return {...props, styles: [...props.styles, tableStyles.base]};
+}`;
+    const output = await applyTransform(input);
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('xstyle: [');
+    expect(output).not.toMatch(/\bstyles:/);
+    expect(output).not.toContain('props.styles');
+  });
+
+  it('renames reads/writes for BodyCellRenderProps', async () => {
+    const input = `const transformBodyCell = (props: BodyCellRenderProps) => ({
+  ...props,
+  styles: [...props.styles, cellStyles.padded],
+});`;
+    const output = await applyTransform(input);
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('xstyle: [');
+    expect(output).not.toContain('props.styles');
+  });
+
+  it('handles all six render-prop interface names as param types', async () => {
+    for (const typeName of [
+      'TableRenderProps',
+      'HeaderRowRenderProps',
+      'HeaderCellRenderProps',
+      'BodyRowRenderProps',
+      'BodyCellRenderProps',
+      'ScrollWrapperRenderProps',
+    ]) {
+      const input = `function t(p: ${typeName}) { return p.styles; }`;
+      const output = await applyTransform(input);
+      expect(output).toContain('p.xstyle');
+      expect(output).not.toContain('p.styles');
+    }
+  });
+
+  it('renames the `styles:` key on a render-prop-shaped object literal (htmlProps + styles siblings)', async () => {
+    const input = `const rp = {htmlProps: {}, styles: []};`;
+    const output = await applyTransform(input);
+    expect(output).toContain('xstyle: []');
+    expect(output).not.toMatch(/\bstyles:/);
+  });
+
+  it('does NOT touch an unrelated `styles` from stylex.create', async () => {
+    const input = `import * as stylex from '@stylexjs/stylex';
+const styles = stylex.create({base: {color: 'red'}});
+function useStuff() {
+  return stylex.props(styles.base);
+}`;
+    const output = await applyTransform(input);
+    // No render-prop binding, no htmlProps-shaped object -> unchanged
+    expect(output).toContain('const styles = stylex.create');
+    expect(output).toContain('styles.base');
+    expect(output).not.toContain('xstyle');
+  });
+
+  it('does NOT rename `.styles` on an unrelated (untyped) object even when a render-prop binding exists elsewhere', async () => {
+    const input = `function transformTable(props: TableRenderProps) {
+  const theme = getTheme();
+  return {...props, styles: [...props.styles, theme.styles.base]};
+}`;
+    const output = await applyTransform(input);
+    // props.styles renamed; theme.styles left alone
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('theme.styles.base');
+  });
+
+  it('returns undefined for files with no render-prop usage', async () => {
+    const {default: transform} = await import(
+      '../rename-table-renderprops-styles-to-xstyle.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `const styles = {a: 1};\nconst x = styles.a;`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined for already-migrated code (xstyle only)', async () => {
+    const {default: transform} = await import(
+      '../rename-table-renderprops-styles-to-xstyle.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `function transformTable(props: TableRenderProps) {
+  return {...props, xstyle: [...props.xstyle]};
+}`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+});

package/src/codemods/transforms/v0.1.7/index.mjs

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.7 transform manifest
+ *
+ * Lists all codemods for the v0.1.7 release in the order they should run.
+ */
+
+import migrateTableTablePropsToDirectProps, {
+  meta as migrateTableTablePropsToDirectPropsMeta,
+} from './migrate-table-tableprops-to-direct-props.mjs';
+import renameTableRenderPropsStylesToXstyle, {
+  meta as renameTableRenderPropsStylesToXstyleMeta,
+} from './rename-table-renderprops-styles-to-xstyle.mjs';
+
+export default [
+  {
+    name: 'migrate-table-tableprops-to-direct-props',
+    transform: migrateTableTablePropsToDirectProps,
+    meta: migrateTableTablePropsToDirectPropsMeta,
+  },
+  {
+    name: 'rename-table-renderprops-styles-to-xstyle',
+    transform: renameTableRenderPropsStylesToXstyle,
+    meta: renameTableRenderPropsStylesToXstyleMeta,
+  },
+];

package/src/codemods/transforms/v0.1.7/migrate-table-tableprops-to-direct-props.mjs

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate Table tableProps to direct root props
+ * @see https://github.com/facebook/astryx/issues/3679
+ *
+ * `tableProps` (typed HTMLAttributes<HTMLTableElement>, nesting HTML
+ * attributes one level deep) is deprecated. As of v0.1.7, <Table> honors
+ * className/style/xstyle directly and spreads all other BaseProps
+ * (id, aria-*, data-*, event handlers, ...) onto the root <table>, with
+ * direct props taking precedence over tableProps.
+ *
+ * This codemod lifts object-literal `tableProps` keys into sibling JSX
+ * props:
+ *
+ * - tableProps={{className: 'x', style: s}} → className="x" style={s}
+ * - String-literal keys ('aria-label', 'data-testid') become hyphenated
+ *   JSX attributes.
+ * - Keys that collide with an existing sibling attribute (or fail the
+ *   attribute-name guard) are kept inside a shrunken tableProps with a
+ *   trailing TODO comment for manual migration.
+ * - Dynamic values (tableProps={props}, tableProps={fn()}, objects with
+ *   spreads/computed keys/methods) are left untouched with a TODO comment.
+ *
+ * Only elements whose name resolves to a `Table` import (alias-aware)
+ * from an Astryx core source are rewritten. No import changes are needed.
+ */
+
+export const meta = {
+  title: 'Migrate Table tableProps to direct root props',
+  description:
+    'Lifts object-literal `tableProps` keys on <Table> into sibling JSX props ' +
+    '(className, style, id, aria-*, data-*, event handlers). Dynamic or ' +
+    'colliding entries are kept and annotated with a TODO comment.',
+  pr: '#3679',
+};
+
+/** Import sources that provide the Astryx Table component. */
+const TABLE_IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Table',
+  '@xds/core',
+  '@xds/core/Table',
+]);
+
+/** Keys must be valid JSX attribute names to be lifted. */
+const LIFTABLE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+const TODO_COMMENT =
+  ' TODO(astryx): tableProps is deprecated — merge these into direct props manually ';
+
+/**
+ * Extract the static key name from an object property, or null when the
+ * property is not a simple liftable entry (spread, computed key, method,
+ * getter/setter, non-string literal key).
+ */
+function getPropertyKeyName(prop) {
+  if (prop.type !== 'ObjectProperty' && prop.type !== 'Property') return null;
+  // espree-style Property nodes: skip methods and accessors
+  if (prop.method || (prop.kind != null && prop.kind !== 'init')) return null;
+  if (prop.computed) return null;
+  const key = prop.key;
+  if (key.type === 'Identifier') return key.name;
+  if (
+    (key.type === 'StringLiteral' || key.type === 'Literal') &&
+    typeof key.value === 'string'
+  ) {
+    return key.value;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Track local names for the Table import (alias-aware) ---
+  const tableLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((path) => {
+    if (!TABLE_IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (spec.type === 'ImportSpecifier' && spec.imported.name === 'Table') {
+        tableLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (tableLocals.size === 0) return undefined;
+
+  function attachTodo(attr) {
+    if (!attr.comments) attr.comments = [];
+    if (attr.comments.some((c) => c.value === TODO_COMMENT)) return;
+    attr.comments.push(j.commentBlock(TODO_COMMENT, false, true));
+    hasChanges = true;
+  }
+
+  function buildAttributeValue(valueNode) {
+    if (
+      valueNode.type === 'StringLiteral' ||
+      (valueNode.type === 'Literal' && typeof valueNode.value === 'string')
+    ) {
+      return j.stringLiteral(valueNode.value);
+    }
+    return j.jsxExpressionContainer(valueNode);
+  }
+
+  // --- 2. Rewrite tableProps on tracked <Table> elements ---
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !tableLocals.has(componentName)) return;
+
+    const attrs = path.node.attributes;
+    const tablePropsAttr = attrs.find(
+      (a) => a.type === 'JSXAttribute' && a.name?.name === 'tableProps',
+    );
+    if (!tablePropsAttr) return;
+
+    const value = tablePropsAttr.value;
+    const isObjectLiteral =
+      value?.type === 'JSXExpressionContainer' &&
+      value.expression.type === 'ObjectExpression';
+
+    // Dynamic case: tableProps={identifier}, tableProps={fn()}, ... —
+    // leave the attribute untouched and warn via a trailing comment
+    // (api.report is a stub; comments are the only warning channel).
+    if (!isObjectLiteral) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const obj = value.expression;
+
+    // Objects containing spreads, computed keys, or methods are treated
+    // as dynamic: no partial lift, just the TODO comment.
+    const allSimple = obj.properties.every(
+      (prop) => getPropertyKeyName(prop) !== null,
+    );
+    if (!allSimple) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const lifted = [];
+    const kept = [];
+    for (const prop of obj.properties) {
+      const keyName = getPropertyKeyName(prop);
+      const collidesWithSibling = attrs.some(
+        (a) => a.type === 'JSXAttribute' && a.name?.name === keyName,
+      );
+      const collidesWithLifted = lifted.some(
+        (a) => a.name.name === keyName,
+      );
+      if (
+        !LIFTABLE_KEY_RE.test(keyName) ||
+        collidesWithSibling ||
+        collidesWithLifted
+      ) {
+        kept.push(prop);
+        continue;
+      }
+      lifted.push(
+        j.jsxAttribute(
+          j.jsxIdentifier(keyName),
+          buildAttributeValue(prop.value),
+        ),
+      );
+    }
+
+    const tablePropsIdx = attrs.indexOf(tablePropsAttr);
+    if (kept.length === 0) {
+      // All keys lifted — replace tableProps with the sibling attributes.
+      attrs.splice(tablePropsIdx, 1, ...lifted);
+      hasChanges = true;
+    } else {
+      // Some keys collide or fail the name guard — keep only those in a
+      // shrunken tableProps and flag it for manual migration.
+      attrs.splice(tablePropsIdx, 0, ...lifted);
+      obj.properties = kept;
+      attachTodo(tablePropsAttr);
+      if (lifted.length > 0) hasChanges = true;
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/codemods/transforms/v0.1.7/rename-table-renderprops-styles-to-xstyle.mjs

@@ -0,0 +1,197 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Table render-prop `styles` field to `xstyle`
+ *
+ * As of v0.1.7, the Table plugin render-prop interfaces
+ * (`TableRenderProps`, `HeaderRowRenderProps`, `HeaderCellRenderProps`,
+ * `BodyRowRenderProps`, `BodyCellRenderProps`, `ScrollWrapperRenderProps`)
+ * and the `scrollWrapper` component contract renamed their StyleX array
+ * field `styles` -> `xstyle`, matching the prop name sub-components
+ * receive it under.
+ *
+ * Custom plugin authors read `props.styles` and write `styles: [...]`
+ * inside their transform functions (`transformTable`, `transformHeaderRow`,
+ * `transformHeaderCell`, `transformBodyRow`, `transformBodyCell`,
+ * `transformScrollWrapper`). This codemod renames those reads and writes.
+ *
+ * A blind global `styles` rename is unsafe — `styles` is also the
+ * conventional local name for a `stylex.create({...})` bag, which is
+ * unrelated. So this transform only rewrites `styles` when it is
+ * *scoped to a render-prop object*: a function parameter (or a variable)
+ * whose TypeScript type annotation is one of the render-prop interfaces.
+ * Within such a scope it rewrites:
+ *
+ *   - `<param>.styles`            -> `<param>.xstyle`   (member reads/writes)
+ *   - `{ ..., styles: [...] }`    -> `{ ..., xstyle: [...] }`
+ *     for object literals that carry the render-prop shape (a sibling
+ *     `htmlProps` key), and object literals assigned/spread from the
+ *     tracked render-prop binding.
+ *
+ * Ambiguous cases that can't be resolved from types alone (e.g. a
+ * render-prop object passed through an untyped variable, or a `styles`
+ * bag from `stylex.create`) are left untouched, so the transform never
+ * renames an unrelated `styles`. This mirrors the conservative,
+ * scope-limited approach of the sibling
+ * `migrate-table-tableprops-to-direct-props` codemod.
+ */
+
+export const meta = {
+  title: 'Rename Table render-prop `styles` field to `xstyle`',
+  description:
+    'Renames the `styles` StyleX-array field to `xstyle` on Table plugin ' +
+    'render-prop objects (TableRenderProps, HeaderRowRenderProps, ' +
+    'HeaderCellRenderProps, BodyRowRenderProps, BodyCellRenderProps, ' +
+    'ScrollWrapperRenderProps) inside plugin transform functions. Reads ' +
+    '(`props.styles`) and writes (`styles: [...]`) are renamed; unrelated ' +
+    '`styles` bindings (e.g. from stylex.create) are left untouched.',
+};
+
+/** The render-prop interface type names whose `styles` field became `xstyle`. */
+const RENDER_PROP_TYPES = new Set([
+  'TableRenderProps',
+  'HeaderRowRenderProps',
+  'HeaderCellRenderProps',
+  'BodyRowRenderProps',
+  'BodyCellRenderProps',
+  'ScrollWrapperRenderProps',
+]);
+
+/** Resolve the base type name from a TS type annotation node. */
+function typeNameOf(typeAnnotation) {
+  // `x: TableRenderProps`
+  const t = typeAnnotation?.typeAnnotation ?? typeAnnotation;
+  if (!t) return null;
+  if (t.type === 'TSTypeReference' && t.typeName?.type === 'Identifier') {
+    return t.typeName.name;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Collect binding names typed as a render-prop interface. ---
+  // Function/arrow params: (props: TableRenderProps) => ...
+  const renderPropBindings = new Set();
+
+  function collectParam(param) {
+    if (
+      param.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(param.typeAnnotation))
+    ) {
+      renderPropBindings.add(param.name);
+    }
+  }
+
+  root
+    .find(j.Function)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionDeclaration)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.ArrowFunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+
+  // Variable declarations: `const rp: BodyCellRenderProps = ...`
+  root.find(j.VariableDeclarator).forEach((p) => {
+    const id = p.node.id;
+    if (
+      id?.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(id.typeAnnotation))
+    ) {
+      renderPropBindings.add(id.name);
+    }
+  });
+
+  const hasTypedBinding = renderPropBindings.size > 0;
+
+  // Also detect object literals that are structurally a render-prop object.
+  // Two shapes qualify:
+  //  1. An `htmlProps` sibling key alongside a `styles`/`xstyle` key — the
+  //     literal shape a transform function returns from scratch.
+  //  2. A spread of a tracked render-prop binding (`{...props, styles: [...]}`)
+  //     — the common "carry the render-prop object forward, override styles"
+  //     shape. (Only counts when `renderPropBindings` is non-empty.)
+  function isRenderPropShapedObject(objExpr) {
+    if (objExpr.type !== 'ObjectExpression') return false;
+    const keyNames = objExpr.properties
+      .map((pr) =>
+        pr.type === 'ObjectProperty' || pr.type === 'Property'
+          ? pr.key?.name ?? pr.key?.value
+          : null,
+      )
+      .filter(Boolean);
+    if (keyNames.includes('htmlProps') && keyNames.includes('styles')) {
+      return true;
+    }
+    // Spread of a tracked render-prop binding.
+    const spreadsRenderProp = objExpr.properties.some(
+      (pr) =>
+        (pr.type === 'SpreadElement' || pr.type === 'ExperimentalSpreadProperty') &&
+        pr.argument?.type === 'Identifier' &&
+        renderPropBindings.has(pr.argument.name),
+    );
+    return spreadsRenderProp && keyNames.includes('styles');
+  }
+
+  if (!hasTypedBinding) {
+    // Nothing is typed as a render-prop interface. Only rewrite clearly
+    // render-prop-shaped object literals (htmlProps + styles siblings);
+    // never touch bare `styles` in this file (too ambiguous).
+    let touched = false;
+    root.find(j.ObjectExpression).forEach((p) => {
+      if (!isRenderPropShapedObject(p.node)) return;
+      for (const prop of p.node.properties) {
+        if (
+          (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+          !prop.computed &&
+          prop.key?.type === 'Identifier' &&
+          prop.key.name === 'styles'
+        ) {
+          prop.key.name = 'xstyle';
+          touched = true;
+        }
+      }
+    });
+    if (!touched) return undefined;
+    return root.toSource({quote: 'single'});
+  }
+
+  // --- 2. Rewrite `<binding>.styles` member access -> `.xstyle`. ---
+  root.find(j.MemberExpression).forEach((p) => {
+    const {object, property, computed} = p.node;
+    if (computed) return;
+    if (property?.type !== 'Identifier' || property.name !== 'styles') return;
+    if (object?.type !== 'Identifier' || !renderPropBindings.has(object.name)) {
+      return;
+    }
+    property.name = 'xstyle';
+    hasChanges = true;
+  });
+
+  // --- 3. Rewrite `styles:` keys on render-prop-shaped object literals. ---
+  root.find(j.ObjectExpression).forEach((p) => {
+    if (!isRenderPropShapedObject(p.node)) return;
+    for (const prop of p.node.properties) {
+      if (
+        (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+        !prop.computed &&
+        prop.key?.type === 'Identifier' &&
+        prop.key.name === 'styles'
+      ) {
+        prop.key.name = 'xstyle';
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/agent-docs.mjs

@@ -197,6 +197,20 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
     lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
   }
   lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
+  // Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/
+  // prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw
+  // CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.
+  // The fix names the sanctioned escape hatch for the configured system.
+  const selfCheckFix = {
+    stylex:
+      'replace any className=, style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
+    tailwind:
+      'replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility',
+    css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
+  };
+  lines.push(
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+  );
   lines.push('');
 
   // Command reference — build/template/component are covered in WORKFLOW above.

package/src/commands/agent-docs.test.mjs

@@ -43,6 +43,26 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/never override --color-/);
   });
 
+  it('includes the post-generation self-check rule', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toContain('SELF-CHECK before you finish');
+    expect(result).toMatch(/re-read the file/);
+    expect(result).toMatch(/don't hand-roll CSS/);
+  });
+
+  it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {
+    // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token
+    const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(stylexSelfCheck).toMatch(/xstyle/);
+    expect(stylexSelfCheck).toMatch(/className=/);
+    // className IS the system in Tailwind — it must NOT be flagged
+    const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(tailwindSelfCheck).toBeDefined();
+    expect(tailwindSelfCheck).not.toMatch(/className=/);
+  });
+
   it('defaults to the CSS-variable styling path (no compiler)', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toMatch(/style\/className with tokens/);

package/src/config.mjs

@@ -1,18 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * Type-preserving helper for the Astryx config file.
- *
- * This is an intentionally tiny runtime identity function: it returns its
- * argument unchanged. Its value is the exported TypeScript surface from
- * `@astryxdesign/cli/config`, so config files get editor/type feedback without
- * coupling to CLI internals. Validation is NOT performed here — it happens at
- * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).
- *
- * @template {import('./types/config').AstryxConfig} T
- * @param {T} config
- * @returns {T}
+ * Re-export of the config-authoring helper, which now lives in
+ * `@astryxdesign/core/config` so an app's config file gets type feedback
+ * without depending on the CLI. Kept here so existing
+ * `@astryxdesign/cli/config` imports continue to work unchanged.
  */
-export function createConfig(config) {
-  return config;
-}
+export {createConfig} from '@astryxdesign/core/config';

package/src/doc.mjs

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc-authoring API (public `@astryxdesign/cli/doc`).
+ *
+ * The `createComponentDoc`/`createFunctionDoc`/`createDoc` authoring helpers now
+ * live in `@astryxdesign/core/authoring` and are re-exported here so existing
+ * `@astryxdesign/cli/doc` imports keep working. The Zod load-boundary schemas
+ * live in `./schemas/doc-schema.mjs` (core-free) and are re-exported here for
+ * back-compat; internal hot-path code imports them from the schema module
+ * directly so it never depends on core's built `dist/`.
+ */
+
+export {
+  createComponentDoc,
+  createFunctionDoc,
+  createDoc,
+} from '@astryxdesign/core/authoring';
+
+export {
+  ComponentDocKindSchema,
+  FunctionDocKindSchema,
+  GenericDocKindSchema,
+  StampedDocSchema,
+  LegacyDocSchema,
+  ComponentDocSchema,
+} from './schemas/doc-schema.mjs';