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

package/api/theme/themeBuild.doc.mjs

@@ -73,7 +73,7 @@ export const doc = {
     {
       type: 'theme.build',
       description:
-        'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and validation warnings—including exact canonical replacements for deprecated component target keys. Resolves to null instead when the theme produced no CSS (nothing to build).',
+        'Build receipt {name, tokenCount, componentCount, sizeKB, outputs, warnings, notices}: the theme name; how many tokens (portable plus theme-local) and component targets it overrides; the CSS size in KB; the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}; warnings, the defects the author should fix, including exact canonical replacements for deprecated component target keys and declarations the generator dropped; and notices, advisories about a correct theme, such as a font it names but does not load. Resolves to null instead when the theme produced no CSS (nothing to build).',
     },
     {
       type: 'theme.build.check',
@@ -87,10 +87,13 @@ export const doc = {
       code: 'ERR_THEME_LOAD',
       when: 'the file cannot be loaded or parsed into a defineTheme() result',
     },
-    {code: 'ERR_THEME_INVALID', when: 'the resolved theme has no name'},
+    {
+      code: 'ERR_THEME_INVALID',
+      when: 'the resolved theme is invalid, for example it has no name, or a custom Heading type has no standalone rule with a declaration the compiler can emit',
+    },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker',
+      when: 'the theme name contains a path separator or traversal marker, or a relative `out` path resolves outside cwd (including through a symlink)',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
@@ -102,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_WRITE_FAILED',
-      when: 'writing the outputs fails (staged temp files are rolled back)',
+      when: 'creating the output directory or writing the outputs fails (staged temp files are rolled back)',
     },
   ],
   examples: [

package/api/theme/themeTemplate.doc.mjs

@@ -51,7 +51,10 @@ export const doc = {
         'Receipt: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success, not a failure.',
     },
   ],
-  throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],
+  throws: [
+    {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
+    {code: 'ERR_WRITE_FAILED', when: 'the template file cannot be written'},
+  ],
   examples: [
     {label: 'Write it at the project root', code: 'themeTemplate();'},
     {

package/api/upgrade/_adapter.mjs

@@ -104,6 +104,27 @@ export function uniqueFiles(files) {
   ];
 }
 
+/**
+ * Run app code with its stdout writes sent to stderr. Stdout carries only the
+ * command's own output, so a hook that prints cannot corrupt `--json`.
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withStdoutOnStderr(fn) {
+  const realWrite = process.stdout.write;
+  process.stdout.write = /** @type {any} */ (
+    function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
+      return process.stderr.write(chunk, ...rest);
+    }
+  );
+  try {
+    return await fn();
+  } finally {
+    process.stdout.write = realWrite;
+  }
+}
+
 /**
  * Run the app config's post-codemod hooks (config.hooks.postCodemod).
  * Dry-run PREVIEWS (buildCommand still called, so a throw fails); apply executes.
@@ -123,7 +144,9 @@ export async function runPostCodemodHooks(hooks, context) {
       );
     }
 
-    const cmd = await hook.buildCommand({packageDir, files});
+    const cmd = await withStdoutOnStderr(() =>
+      hook.buildCommand({packageDir, files}),
+    );
     if (!cmd) {
       logger.log(`Post-codemod hook ${label} produced no command; skipping.`);
       continue;
@@ -147,7 +170,7 @@ export async function runPostCodemodHooks(hooks, context) {
         env: {...process.env, ...(cmd.options?.env ?? {})},
       }),
     );
-    logger.log(`✓ Post-codemod hook ${label} completed.`);
+    logger.log(`[ok] Post-codemod hook ${label} completed.`);
   }
 }
 
@@ -186,7 +209,7 @@ export async function prepareAgentDocsRefresh({
   if (initial.status === 'missing') {
     summary.action = 'nudge-init';
     logger.warn(
-      `No Astryx agent-docs block found — AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
+      `No Astryx agent-docs block found - AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
     );
     return {cwd, renderedBlock: null, summary};
   }
@@ -240,7 +263,7 @@ export function applyAgentDocsRefresh(plan) {
     summary.files = written;
     summary.action = summary.refreshed ? 'refreshed' : 'error';
     if (summary.refreshed) {
-      logger.log(`✓ Agent docs refreshed → ${written.join(', ')}`);
+      logger.log(`[ok] Agent docs refreshed -> ${written.join(', ')}`);
     } else {
       logger.warn(
         `Agent docs look stale but couldn't be refreshed. Run \`${formatCliCommand('astryx init --features agents')}\` to reinstall the block.`,

package/api/upgrade/list/list.mjs

@@ -10,6 +10,7 @@
 
 import {collectAllCodemods} from '../_adapter.mjs';
 import {logger} from '../../logger.mjs';
+import {toAscii} from '../../../assets/codemods/term-log.mjs';
 
 /**
  * List every available codemod (oldest→newest).
@@ -19,7 +20,7 @@ export async function list() {
   const codemods = await collectAllCodemods();
   logger.log('Available codemods:');
   for (const {name, title, pr, optional} of codemods) {
-    logger.log(`  ${name} — ${title}${optional ? ' (optional)' : ''} (${pr})`);
+    logger.log(`  ${name} - ${toAscii(title)}${optional ? ' (optional)' : ''} (${pr})`);
   }
   logger.log('Done\n');
   return {

package/api/upgrade/list/list.test.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the upgrade.list leaf: every field an entry
+ * carries is declared on the canonical `UpgradeListEntry` type, and every
+ * declared field is present on every entry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import ts from 'typescript';
+import {list} from './list.mjs';
+
+const TYPE_FILE = fileURLToPath(
+  new URL('../upgrade.type.mjs', import.meta.url),
+);
+
+/**
+ * Property names a JSDoc `@typedef {object}` declares, parsed from the file.
+ * @param {string} typedefName
+ * @returns {string[]}
+ */
+function declaredProperties(typedefName) {
+  const source = ts.createSourceFile(
+    TYPE_FILE,
+    fs.readFileSync(TYPE_FILE, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  );
+  /** @type {string[]} */
+  const names = [];
+  for (const statement of source.statements) {
+    for (const doc of /** @type {any} */ (statement).jsDoc ?? []) {
+      for (const tag of doc.tags ?? []) {
+        if (
+          !ts.isJSDocTypedefTag(tag) ||
+          tag.name?.getText(source) !== typedefName
+        ) {
+          continue;
+        }
+        const literal = tag.typeExpression;
+        if (literal && ts.isJSDocTypeLiteral(literal)) {
+          for (const property of literal.jsDocPropertyTags ?? []) {
+            names.push(property.name.getText(source));
+          }
+        }
+      }
+    }
+  }
+  return names.sort();
+}
+
+describe('upgrade.list entries', () => {
+  it('carry exactly the fields UpgradeListEntry declares', async () => {
+    const declared = declaredProperties('UpgradeListEntry');
+    expect(declared.length).toBeGreaterThan(0);
+
+    const {type, data} = await list();
+    expect(type).toBe('upgrade.list');
+    expect(data.length).toBeGreaterThan(0);
+    for (const entry of data) {
+      expect(Object.keys(entry).sort()).toEqual(declared);
+    }
+  });
+
+  it('marks optional codemods with a boolean', async () => {
+    const {data} = await list();
+    for (const entry of data) expect(typeof entry.optional).toBe('boolean');
+    expect(data.some(entry => entry.optional)).toBe(true);
+  });
+});

package/api/upgrade/status/status.mjs

@@ -24,7 +24,7 @@ import {logger} from '../../logger.mjs';
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
 export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
-  logger.log('✓ Already up to date — no codemods to run.');
+  logger.log('[ok] Already up to date - no codemods to run.');
   logger.log('Use --force to run codemods anyway.');
   logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
   return {
@@ -45,7 +45,7 @@ export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
 export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
-  logger.log('✓ No codemods available for this version range.');
+  logger.log('[ok] No codemods available for this version range.');
   logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
   return {
     type: 'upgrade.status',

package/api/upgrade/upgrade.doc.mjs

@@ -80,7 +80,8 @@ export const doc = {
     {
       name: 'options.installDeps',
       type: 'boolean',
-      description: 'Auto-install jscodeshift without prompting.',
+      description:
+        'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
     },
     {
       name: 'options.registry',

package/api/upgrade/upgrade.type.d.mts

@@ -12,6 +12,10 @@ export type UpgradeListEntry = {
     name: string;
     title: string;
     version: string;
+    /**
+     * True when the codemod runs only if named with `--codemod`.
+     */
+    optional: boolean;
 };
 /**
  * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)

package/api/upgrade/upgrade.type.mjs

@@ -25,6 +25,7 @@
  * @property {string} name
  * @property {string} title
  * @property {string} version
+ * @property {boolean} optional True when the codemod runs only if named with `--codemod`.
  */
 
 /**

package/assets/codemods/term-log.mjs

@@ -11,6 +11,8 @@
  * `p.log.step(...)`, `p.log.success(...)`, etc. All output routes through
  * `humanLog`, the CLI's stdout-discipline primitive, which is a no-op in
  * `--json` mode — so these human logs can never corrupt a JSON envelope.
+ * Every line is plain ASCII: level prefixes are ASCII and typographic glyphs
+ * in a message are transliterated before it is printed.
  *
  * The side-effecting API commands (upgrade/init/themeBuild) do NOT use this;
  * they write through the shared `logger` (api/logger.mjs).
@@ -18,8 +20,30 @@
 
 import {humanLog} from '../../foundation/response/json.mjs';
 
-/** @param {unknown} msg */
-const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
+/** @type {Array<[RegExp, string]>} */
+const ASCII_GLYPHS = [
+  [/[\u2014\u2013]/g, '-'],
+  [/\u2192/g, '->'],
+  [/\u2713/g, '[ok]'],
+  [/\u2717/g, '!!'],
+  [/\u26a0\ufe0f?/g, '!'],
+  [/\u2022/g, '-'],
+  [/\u2026/g, '...'],
+  [/[\u2018\u2019]/g, "'"],
+  [/[\u201c\u201d]/g, '"'],
+  [/\u00a0/g, ' '],
+];
+
+/**
+ * A message as plain ASCII: typographic glyphs become their ASCII spelling.
+ * @param {unknown} msg
+ * @returns {string}
+ */
+export function toAscii(msg) {
+  let text = msg === undefined || msg === null ? '' : String(msg);
+  for (const [glyph, ascii] of ASCII_GLYPHS) text = text.replace(glyph, ascii);
+  return text;
+}
 
 /**
  * Human-facing log surface (the small `log` API codemods use). All lines go to
@@ -28,15 +52,15 @@ const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
  */
 export const log = {
   /** @param {unknown} msg */
-  message: (msg) => humanLog(toStr(msg)),
+  message: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  info: (msg) => humanLog(toStr(msg)),
+  info: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  step: (msg) => humanLog(toStr(msg)),
+  step: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  success: (msg) => humanLog(`✓ ${toStr(msg)}`),
+  success: (msg) => humanLog(`[ok] ${toAscii(msg)}`),
   /** @param {unknown} msg */
-  warn: (msg) => humanLog(`⚠ ${toStr(msg)}`),
+  warn: (msg) => humanLog(`! ${toAscii(msg)}`),
   /** @param {unknown} msg */
-  error: (msg) => humanLog(`✗ ${toStr(msg)}`),
+  error: (msg) => humanLog(`!! ${toAscii(msg)}`),
 };

package/assets/codemods/term-log.test.mjs

@@ -51,7 +51,7 @@ describe('sanity: helpers are live in human mode', () => {
     setJsonMode(false);
     p.log.success('done');
     expect(logSpy).toHaveBeenCalledTimes(1);
-    expect(logSpy).toHaveBeenCalledWith('✓ done');
+    expect(logSpy).toHaveBeenCalledWith('[ok] done');
   });
 
   it('every log helper emits exactly one stdout line in human mode', () => {
@@ -60,3 +60,21 @@ describe('sanity: helpers are live in human mode', () => {
     expect(logSpy).toHaveBeenCalledTimes(6);
   });
 });
+
+describe('ASCII output', () => {
+  it('prints ASCII level prefixes and transliterates glyphs in messages', () => {
+    setJsonMode(false);
+    p.log.success('src/a.tsx');
+    p.log.warn('stale \u2014 refresh');
+    p.log.error('    \u2717 src/b.tsx \u2014 rename \u2192 failed');
+    p.log.info('  \u2022 name \u2014 title\u2026');
+    const lines = logSpy.mock.calls.map(call => call.join(' '));
+    expect(lines).toEqual([
+      '[ok] src/a.tsx',
+      '! stale - refresh',
+      '!!     !! src/b.tsx - rename -> failed',
+      '  - name - title...',
+    ]);
+    for (const line of lines) expect(line).not.toMatch(/[\u0080-\uFFFF]/);
+  });
+});

package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs

@@ -220,4 +220,51 @@ function wrapper(useResizable) {
     const output = await apply('rename-resizable-pixel-bounds', input);
     expect(output).toBe(input);
   });
+
+  it('renames bounds when useResizable comes from a namespace import', async () => {
+    const input = `import * as Astryx from '@astryxdesign/core';
+const region = Astryx.useResizable({defaultSize: 240, minSizePx: 120, maxSizePx: 480});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).toContain('maxSize: 480');
+    expect(output).not.toContain('minSizePx');
+    expect(output).not.toContain('maxSizePx');
+  });
+
+  it('leaves a namespace that does not come from Astryx alone', async () => {
+    const input = `import * as Other from 'other-resizable';
+const region = Other.useResizable({minSizePx: 120});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSizePx: 120');
+  });
+
+  it('does not rewrite a parameter that shadows the namespace import', async () => {
+    const input = `import * as Astryx from '@astryxdesign/core';
+function build(Astryx) {
+  return Astryx.useResizable({minSizePx: 120});
+}`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSizePx: 120');
+  });
+
+  it.each([
+    ['as const', '{defaultSize: 240, minSizePx: 120} as const'],
+    ['satisfies', '{defaultSize: 240, minSizePx: 120} satisfies object'],
+  ])('renames a static configuration wrapped in %s', async (_label, config) => {
+    const input = `import {useResizable} from '@astryxdesign/core/Resizable';
+const region = useResizable(${config});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).not.toContain('minSizePx');
+  });
+
+  it('renames wrapped multi-region configurations', async () => {
+    const input = `import {useResizable} from '@astryxdesign/core';
+const regions = useResizable({regions: {
+  nav: {defaultSize: 240, minSizePx: 120} as const,
+} as const});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).not.toContain('minSizePx');
+  });
 });

package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs

@@ -8,6 +8,9 @@
  * released conflict rule (the unified property wins when both are present).
  * A spread or computed property can change precedence invisibly, so dynamic
  * objects stay unchanged and receive a manual-migration TODO instead.
+ * Named and namespace imports both count, and a type-only wrapper (`as`,
+ * `satisfies`, a non-null assertion, parentheses) does not make a
+ * configuration dynamic.
  */
 
 export const meta = {
@@ -33,6 +36,26 @@ const MANUAL_MIGRATION_COMMENT =
   'or computed property. Rename minSizePx/maxSizePx to minSize/maxSize ' +
   'manually without changing property precedence. ';
 
+const TYPE_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/**
+ * The expression under type-only wrappers such as `{...} as const`.
+ * @param {any} node
+ */
+function unwrap(node) {
+  let current = node;
+  while (current && TYPE_WRAPPERS.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
 /** @param {any} property */
 function staticPropertyName(property) {
   if (property.computed) return null;
@@ -128,6 +151,8 @@ export default function transformer(file, api) {
   const root = j(file.source);
   /** @type {Map<string, any>} */
   const bindings = new Map();
+  /** @type {Map<string, any>} */
+  const namespaces = new Map();
 
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     if (!IMPORT_SOURCES.has(path.node.source.value)) return;
@@ -138,17 +163,40 @@ export default function transformer(file, api) {
       ) {
         const local = specifier.local?.name ?? 'useResizable';
         bindings.set(local, path.scope.lookup(local) ?? path.scope);
+      } else if (specifier.type === 'ImportNamespaceSpecifier') {
+        const local = specifier.local.name;
+        namespaces.set(local, path.scope.lookup(local) ?? path.scope);
       }
     }
   });
-  if (bindings.size === 0) return undefined;
+  if (bindings.size === 0 && namespaces.size === 0) return undefined;
+
+  /**
+   * @param {any} callee
+   * @param {any} scope
+   */
+  const isUseResizable = (callee, scope) => {
+    if (callee.type === 'Identifier') {
+      return (
+        bindings.has(callee.name) &&
+        scope.lookup(callee.name) === bindings.get(callee.name)
+      );
+    }
+    return (
+      callee.type === 'MemberExpression' &&
+      !callee.computed &&
+      callee.object.type === 'Identifier' &&
+      callee.property.type === 'Identifier' &&
+      callee.property.name === 'useResizable' &&
+      namespaces.has(callee.object.name) &&
+      scope.lookup(callee.object.name) === namespaces.get(callee.object.name)
+    );
+  };
 
   let changed = false;
   root.find(j.CallExpression).forEach((/** @type {any} */ path) => {
-    const callee = path.node.callee;
-    if (callee.type !== 'Identifier' || !bindings.has(callee.name)) return;
-    if (path.scope.lookup(callee.name) !== bindings.get(callee.name)) return;
-    const config = path.node.arguments[0];
+    if (!isUseResizable(path.node.callee, path.scope)) return;
+    const config = unwrap(path.node.arguments[0]);
     if (config?.type !== 'ObjectExpression') return;
 
     changed = migrateObject(j, config) || changed;
@@ -158,13 +206,12 @@ export default function transformer(file, api) {
         staticPropertyName(property) === 'regions',
     );
     if (!regions || !('value' in regions)) return;
-    const regionsObject = regions.value;
+    const regionsObject = unwrap(regions.value);
     if (regionsObject?.type !== 'ObjectExpression') return;
     for (const region of regionsObject.properties) {
-      if (!('value' in region) || region.value?.type !== 'ObjectExpression') {
-        continue;
-      }
-      changed = migrateObject(j, region.value) || changed;
+      const regionConfig = 'value' in region ? unwrap(region.value) : null;
+      if (regionConfig?.type !== 'ObjectExpression') continue;
+      changed = migrateObject(j, regionConfig) || changed;
     }
   });