@astryxdesign/cli 0.1.1 → 0.1.2-canary.2149fa3

package/src/api/theme-add.mjs

@@ -0,0 +1,182 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for `astryx theme add` — copies a bundled theme's
+ * source (`templates/themes/`, see scripts/generate-cli-themes.mjs) into the
+ * consumer's project so they own it, without needing the theme package.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT} from '../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+const THEMES_DIR = path.join(CLI_ROOT, 'templates', 'themes');
+const MANIFEST_PATH = path.join(THEMES_DIR, 'manifest.json');
+
+// Stripped from scaffolded files so the consumer's copy doesn't carry our
+// repo boilerplate (mirrors the docsite). Preserves a leading BOM/shebang.
+const META_COPYRIGHT_HEADER_RE =
+  /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ Copyright \(c\) Meta Platforms, Inc\. and affiliates\.\r?\n(?:\r?\n)*/;
+
+function stripCopyrightHeader(source) {
+  return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
+}
+
+/** Parsed `themes` array from the bundle manifest (empty if not generated). */
+export function listThemes() {
+  if (!fs.existsSync(MANIFEST_PATH)) return [];
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8'));
+  } catch (err) {
+    throw new AstryxError(
+      `Theme bundle manifest is unreadable (${MANIFEST_PATH}): ${err.message}`,
+      undefined,
+      ERROR_CODES.ERR_NO_SOURCE,
+    );
+  }
+  return Array.isArray(manifest.themes) ? manifest.themes : [];
+}
+
+function findTheme(slug) {
+  if (!slug) return undefined;
+  const lc = String(slug).toLowerCase();
+  return listThemes().find(t => t.slug.toLowerCase() === lc);
+}
+
+function defaultTargetDir(slug) {
+  return path.join('src', 'themes', slug);
+}
+
+/**
+ * Resolve the scaffold plan for `theme add`. Returns the theme list when no
+ * slug (or `list`); otherwise copies the theme's files into the destination
+ * (defaults to `src/themes/<slug>/`).
+ *
+ * @param {string} [slug]
+ * @param {{list?: boolean, targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {Promise<{type: string, data: unknown}>}
+ */
+export async function themeAdd(slug, options = {}) {
+  const {list = false, targetPath, overwrite = false, cwd = process.cwd()} =
+    options;
+  const themes = listThemes();
+
+  if (list || !slug) {
+    return {
+      type: 'theme.list',
+      data: themes.map(t => ({
+        slug: t.slug,
+        displayName: t.displayName,
+        description: t.description,
+        maintained: t.maintained,
+      })),
+    };
+  }
+
+  const match = findTheme(slug);
+  if (!match) {
+    throw new AstryxError(
+      `Unknown theme "${slug}"`,
+      themes.map(t => ({
+        name: t.slug,
+        reason: t.maintained ? 'maintained theme' : 'example theme',
+      })),
+      ERROR_CODES.ERR_UNKNOWN_THEME,
+    );
+  }
+
+  const themeSrcDir = path.join(THEMES_DIR, match.slug);
+
+  // Path-safe destination; reject traversal outside cwd.
+  const rawTarget = targetPath || defaultTargetDir(match.slug);
+  let resolvedDir;
+  try {
+    resolvedDir = assertWithin(rawTarget, cwd, {label: 'theme target path'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(
+        err.message,
+        undefined,
+        ERROR_CODES.ERR_PATH_TRAVERSAL,
+      );
+    }
+    throw err;
+  }
+
+  const writes = match.files.map(name => ({
+    name,
+    src: path.join(themeSrcDir, name),
+    dest: path.join(resolvedDir, name),
+  }));
+  for (const w of writes) {
+    if (!fs.existsSync(w.src)) {
+      throw new AstryxError(
+        `Theme "${match.slug}" is missing bundled file "${w.name}". ` +
+          `Re-run \`node scripts/generate-cli-themes.mjs\` to rebuild the bundle.`,
+        undefined,
+        ERROR_CODES.ERR_NO_SOURCE,
+      );
+    }
+  }
+
+  // Refuse to clobber unless --overwrite.
+  if (!overwrite) {
+    const existing = writes.find(w => fs.existsSync(w.dest));
+    if (existing) {
+      const rel = path.relative(cwd, existing.dest) || existing.dest;
+      throw new AstryxError(
+        `Refusing to overwrite existing file ${rel}. ` +
+          `Re-run with --overwrite (or -f) to replace it.`,
+        undefined,
+        ERROR_CODES.ERR_FILE_EXISTS,
+      );
+    }
+  }
+
+  // Stage to temp files then rename, rolling back partials on failure so a
+  // failed write never leaves a half-written theme.
+  fs.mkdirSync(resolvedDir, {recursive: true});
+  const staged = [];
+  try {
+    for (const w of writes) {
+      const tmp = `${w.dest}.${process.pid}.tmp`;
+      const contents = stripCopyrightHeader(fs.readFileSync(w.src, 'utf-8'));
+      fs.writeFileSync(tmp, contents);
+      staged.push({tmp, dest: w.dest});
+    }
+    for (const s of staged) {
+      fs.renameSync(s.tmp, s.dest);
+    }
+  } catch (err) {
+    for (const s of staged) {
+      try {
+        fs.rmSync(s.tmp, {force: true});
+      } catch {
+        /* best-effort */
+      }
+    }
+    throw new AstryxError(
+      `Failed to write theme files: ${err.message}`,
+      undefined,
+      ERROR_CODES.ERR_WRITE_FAILED,
+    );
+  }
+
+  const relDir = path.relative(cwd, resolvedDir) || '.';
+  return {
+    type: 'theme.add',
+    data: {
+      slug: match.slug,
+      displayName: match.displayName,
+      maintained: match.maintained,
+      outputDir: relDir,
+      entry: match.entry,
+      exportName: match.exportName,
+      files: match.files,
+    },
+  };
+}

package/src/codemods/__tests__/registry.test.mjs

@@ -17,6 +17,7 @@ describe('registry', () => {
         '0.0.14',
         '0.0.15',
         '0.1.0',
+        '0.1.2',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -18,6 +18,7 @@ const registry = new Map([
   ['0.0.14', () => import('./transforms/v0.0.14/index.mjs')],
   ['0.0.15', () => import('./transforms/v0.0.15/index.mjs')],
   ['0.1.0', () => import('./transforms/v0.1.0/index.mjs')],
+  ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/src/codemods/transforms/v0.1.2/__tests__/rename-text-color-active-to-accent.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../rename-text-color-active-to-accent.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-text-color-active-to-accent', () => {
+  it('renames Text color="active" to color="accent"', async () => {
+    const input = `<Text color="active">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Heading color="active" to color="accent"', async () => {
+    const input = `<Heading level={2} color="active">Title</Heading>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Link color="active" to color="accent"', async () => {
+    const input = `<Link href="/x" color="active">Go</Link>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Timestamp color="active" to color="accent"', async () => {
+    const input = `<Timestamp value={d} color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it("renames expression-container color={'active'}", async () => {
+    const input = `<Text color={'active'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('renames active inside a ternary color expression', async () => {
+    const input = `<Text color={isOn ? 'active' : 'secondary'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).toContain("'secondary'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not change other color values', async () => {
+    const input = `<Text color="secondary">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch color="active" on non-target components', async () => {
+    const input = `<StatusDot color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch unrelated "active" string literals', async () => {
+    const input = `const node = {id: 'active', label: 'Active Users'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch a status enum value named active', async () => {
+    const input = `const filters = {status: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames object color prop in files importing a target component', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("color: 'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it("renames color: 'active' as const in files importing a target component", async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const COLORS = [{color: 'active' as const, description: 'Accent'}];`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent' as const");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not rename object color prop when no target component is imported', async () => {
+    const input = `const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames active in Storybook color argTypes options', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const meta = {argTypes: {color: {control: 'select', options: ['primary', 'active', 'inherit']}}};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('returns undefined (no change) when nothing matches', async () => {
+    const input = `<Text color="primary">Hi</Text>`;
+    const output = await applyTransform(input);
+    // applyTransform falls back to source when transform returns undefined
+    expect(output).toBe(input);
+  });
+});

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

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.2 transform manifest
+ *
+ * Lists all codemods for the v0.1.2 release in the order they should run.
+ */
+
+import renameTextColorActiveToAccent, {
+  meta as renameTextColorActiveToAccentMeta,
+} from './rename-text-color-active-to-accent.mjs';
+
+export default [
+  {
+    name: 'rename-text-color-active-to-accent',
+    transform: renameTextColorActiveToAccent,
+    meta: renameTextColorActiveToAccentMeta,
+  },
+];

package/src/codemods/transforms/v0.1.2/rename-text-color-active-to-accent.mjs

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Text/Heading/Link/Timestamp color "active" to "accent"
+ * @see https://github.com/facebook/astryx/issues/2863
+ *
+ * The `active` text-color value is renamed to `accent` and now maps to the
+ * dedicated `--color-text-accent` token (legible accent ink) instead of
+ * `--color-accent` (the interactive/base accent surface). This gives a
+ * first-class, type-safe way to render accent-colored text and resolves the
+ * gap reported in #2863.
+ *
+ * Transforms (scoped to Text, Heading, Link, and Timestamp):
+ * - <Text color="active" />            → <Text color="accent" />
+ * - <Heading color={'active'} />       → <Heading color={'accent'} />
+ * - <Text color={cond ? 'active' : x}> → <Text color={cond ? 'accent' : x}>
+ * - Storybook argTypes: color: { options: [..., 'active', ...] }
+ *     → replaces 'active' with 'accent' (files importing a target component)
+ * - Object properties: { color: 'active' } / { color: 'active' as const }
+ *     → { color: 'accent' } (files importing a target component)
+ *
+ * The transform deliberately does NOT touch bare `'active'` strings that are
+ * not a `color` value (e.g. status enums, ids, filter values), so it is safe
+ * to run across an entire codebase.
+ */
+
+export const meta = {
+  title: 'Rename Text/Heading/Link/Timestamp color "active" to "accent"',
+  description:
+    'Renames the `color="active"` value to `color="accent"` on Text, Heading, ' +
+    'Link, and Timestamp. The `accent` value maps to `--color-text-accent` ' +
+    '(the dedicated accent text ink). Also updates Storybook color argTypes ' +
+    'options and object-literal `color` props in files that import a target component.',
+  pr: '#2863',
+};
+
+const OLD_VALUE = 'active';
+const NEW_VALUE = 'accent';
+
+/** Components whose `color` prop accepts a TextColor value. */
+const TARGET_COMPONENTS = new Set(['Text', 'Heading', 'Link', 'Timestamp']);
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Rewrite a string-literal node when it equals the old value. */
+  function renameStringLiteral(node) {
+    if (!node) return false;
+    if (
+      (node.type === 'StringLiteral' || node.type === 'Literal') &&
+      node.value === OLD_VALUE
+    ) {
+      node.value = NEW_VALUE;
+      if (node.raw) node.raw = `'${NEW_VALUE}'`;
+      return true;
+    }
+    return false;
+  }
+
+  /** Recursively rewrite the old value inside ternary/logical expressions. */
+  function renameInExpression(node) {
+    if (!node) return false;
+    let changed = false;
+    if (node.type === 'StringLiteral' || node.type === 'Literal') {
+      changed = renameStringLiteral(node) || changed;
+    } else if (node.type === 'ConditionalExpression') {
+      changed = renameInExpression(node.consequent) || changed;
+      changed = renameInExpression(node.alternate) || changed;
+    } else if (node.type === 'LogicalExpression') {
+      changed = renameInExpression(node.left) || changed;
+      changed = renameInExpression(node.right) || changed;
+    } else if (node.type === 'TSAsExpression') {
+      // `'active' as const` → rewrite the inner expression
+      changed = renameInExpression(node.expression) || changed;
+    }
+    return changed;
+  }
+
+  // --- 1. JSX attribute: color="active" / color={'active'} on target components ---
+  root.find(j.JSXOpeningElement).forEach(path => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !TARGET_COMPONENTS.has(componentName)) return;
+
+    path.node.attributes.forEach(attr => {
+      if (attr.type !== 'JSXAttribute') return;
+      if (!attr.name || attr.name.name !== 'color') return;
+
+      const value = attr.value;
+      if (!value) return;
+
+      if (value.type === 'StringLiteral' || value.type === 'Literal') {
+        if (renameStringLiteral(value)) hasChanges = true;
+      } else if (value.type === 'JSXExpressionContainer') {
+        if (renameInExpression(value.expression)) hasChanges = true;
+      }
+    });
+  });
+
+  // Object-property / argTypes transforms only run in files that use a target
+  // component — keeps unrelated `{ color: 'active' }` / `'active'` strings safe.
+  const importsTarget =
+    root
+      .find(j.ImportSpecifier)
+      .filter(p => TARGET_COMPONENTS.has(p.node.imported?.name))
+      .size() > 0;
+
+  if (importsTarget) {
+    const PropertyType = j.ObjectProperty ?? j.Property;
+
+    // --- 2. Object property: { color: 'active' } / { color: 'active' as const } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      if (renameInExpression(path.node.value)) hasChanges = true;
+    });
+
+    // --- 3. Storybook argTypes: color: { options: [..., 'active', ...] } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      const value = path.node.value;
+      if (!value || value.type !== 'ObjectExpression') return;
+
+      const optionsProp = value.properties.find(
+        p => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp && optionsProp.value.type === 'ArrayExpression') {
+        optionsProp.value.elements.forEach(el => {
+          if (renameStringLiteral(el)) hasChanges = true;
+        });
+      }
+    });
+  }
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/build-theme.import-path.test.mjs

@@ -77,7 +77,7 @@ afterEach(() => {
 });
 
 describe('theme build install-instructions import path', () => {
-  it('emits ./<name> (no double slash) when out dir equals cwd', () => {
+  it('emits bare ./<name> specifiers (no double slash) when out dir equals cwd', () => {
     // Source theme lives directly in the project root, so the output dir
     // is the cwd and the relative dir is an empty string.
     const project = path.join(tmpDir, 'project');
@@ -97,7 +97,7 @@ describe('theme build install-instructions import path', () => {
     expect(result.stdout).toContain('href="./cwd-theme.css"');
   });
 
-  it('emits ./<sub>/<name> when out dir is a subdirectory of cwd', () => {
+  it('keeps the subdir in the import path for a non-src subdirectory build', () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(path.join(project, 'themes'), 'sub-theme');
 
@@ -112,4 +112,24 @@ describe('theme build install-instructions import path', () => {
     expect(result.stdout).toContain("import './themes/sub-theme.css'");
     expect(result.stdout).toContain('href="./themes/sub-theme.css"');
   });
+
+  it('strips a leading src/ from the import path (relative to a file in src/)', () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(
+      path.join(project, 'src', 'themes', 'ocean'),
+      'ocean',
+    );
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).not.toContain('.//');
+    // The leading src/ is dropped, but themes/ocean/ is kept (people need it).
+    expect(result.stdout).toContain("from './themes/ocean/ocean'");
+    expect(result.stdout).toContain("import './themes/ocean/ocean.css'");
+    expect(result.stdout).not.toContain('./src/');
+  });
 });