@astryxdesign/cli 0.4.2-canary.b2057d1 → 0.4.2-canary.bb07062

package/api/theme/build/build.mjs

@@ -591,6 +591,30 @@ const themeScopeStart = (/** @type {string} */ name) =>
   `[data-astryx-theme="${name}"]`;
 const THEME_SCOPE_TO = `[data-astryx-theme]`;
 
+/**
+ * Module extensions the theme loader resolves, source before artifact.
+ *
+ * `theme build` writes `<name>.js` next to `<name>.ts`, and jiti's default
+ * order tries `.js` first — so once a base theme had been built, every sibling
+ * theme that `extends` it resolved to that generated artifact instead of the
+ * source. The artifact carries no `components` and exports a different name,
+ * so the inheritance silently evaporated. Resolving source first is also what
+ * the author's TypeScript sees, which is the point: the CSS the build emits
+ * matches the theme they type-checked.
+ */
+const THEME_MODULE_EXTENSIONS = [
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '.mtsx',
+  '.ctsx',
+  '.mjs',
+  '.cjs',
+  '.js',
+  '.json',
+];
+
 /**
  * Import a theme module using jiti and find the defineTheme() result.
  * Returns the resolved DefinedTheme object.
@@ -601,6 +625,7 @@ async function importThemeModule(filePath) {
   const jiti = createJiti(import.meta.url, {
     moduleCache: false,
     jsx: true,
+    extensions: THEME_MODULE_EXTENSIONS,
   });
 
   const mod = await jiti.import(filePath, {default: true});
@@ -733,6 +758,13 @@ function extractIconInfo(filePath) {
  * Includes the theme name, marker, and re-exports the icon registry.
  * All styling is in the CSS file.
  *
+ * The module carries the theme's resolved `components` and on-media surfaces
+ * alongside its tokens. They are not needed to apply the theme — the CSS holds
+ * all of that — but a built theme is a legitimate base for `extends` (the
+ * shipped themes expose one as their `./built` subpath), and a base that
+ * carries only tokens makes its children silently lose every component
+ * override it had.
+ *
  * The icon registry is imported rather than inlined because it holds React
  * elements, which cannot be serialized. `extractIconInfo` lifts the specifier
  * out of the TypeScript source, where an extensionless `./icons` is resolved by
@@ -774,6 +806,27 @@ function generateBuiltModule(themeDef, iconInfo, iconsSpecifier) {
     .map((line, i) => (i === 0 ? line : '  ' + line))
     .join('\n');
 
+  /**
+   * Serialize a resolved theme field as an indented object literal, or '' when
+   * there is nothing to emit.
+   * @param {string} field
+   * @param {unknown} value
+   * @returns {string}
+   */
+  const serializeField = (field, value) => {
+    if (!value || Object.keys(value).length === 0) return '';
+    const body = JSON.stringify(value, null, 2)
+      .split('\n')
+      .map((line, i) => (i === 0 ? line : '  ' + line))
+      .join('\n');
+    return `  ${field}: ${body},\n`;
+  };
+
+  const inheritableFields =
+    serializeField('components', themeDef.components) +
+    serializeField('__onDark', themeDef.__onDark) +
+    serializeField('__onLight', themeDef.__onLight);
+
   return `${iconImport}/**
  * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
  * Import the CSS file alongside this module:
@@ -785,7 +838,7 @@ export const ${toIdentifier(themeDef.name)}Theme = {
   name: '${themeDef.name}',
   __built: true,
   tokens: ${tokensStr},
-${iconsField}
+${inheritableFields}${iconsField}
 };
 ${iconReExport}`;
 }
@@ -1099,20 +1152,29 @@ export async function themeBuild(
   let css;
   let resolvedTheme;
   {
-    // jiti returns an already-resolved theme; legacy eval returns raw input.
-    const isAlreadyResolved =
-      !themeDef.typography && !themeDef.motion && !themeDef.radius;
-    if (isAlreadyResolved) {
-      resolvedTheme = themeDef;
+    // jiti returns an already-resolved theme; a plain object literal (or the
+    // legacy eval path) returns raw defineTheme input, which still has to go
+    // through the resolver. Detect that by the input-only fields — a resolved
+    // theme has none of them — and hand the WHOLE object over: picking fields
+    // by name is how `extends` (and `color`, and `syntax`) used to be dropped
+    // on the way in.
+    const INPUT_ONLY_FIELDS = [
+      'extends',
+      'typography',
+      'motion',
+      'radius',
+      'color',
+      'syntax',
+      'onDark',
+      'onLight',
+    ];
+    const needsResolution = INPUT_ONLY_FIELDS.some(
+      field => themeDef[field] !== undefined,
+    );
+    if (needsResolution) {
+      resolvedTheme = _defineTheme({...themeDef});
     } else {
-      resolvedTheme = _defineTheme({
-        name: themeDef.name,
-        typography: themeDef.typography,
-        motion: themeDef.motion,
-        radius: themeDef.radius,
-        tokens: themeDef.tokens,
-        components: themeDef.components,
-      });
+      resolvedTheme = themeDef;
     }
     const scopeSelector = themeScopeStart(themeDef.name);
     const scopeTo = THEME_SCOPE_TO;

package/api/theme/build/build.test.mjs

@@ -323,6 +323,180 @@ describe('themeBuild() — the shipped theme template', () => {
     expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
     // The template teaches custom variants; the augmentation it promises the
     // reader has to actually be generated.
-    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(
+      true,
+    );
+  });
+});
+
+describe('themeBuild() — extends', () => {
+  // These fixtures `import {defineTheme} from '@astryxdesign/core/theme'` the
+  // way a real theme file does, so they have to sit somewhere that specifier
+  // resolves — an OS temp dir has no node_modules above it.
+  let extDir;
+  beforeEach(() => {
+    extDir = fs.mkdtempSync(
+      path.join(path.resolve(import.meta.dirname, '../../..'), '.tmp-extends-'),
+    );
+  });
+  afterEach(() => {
+    fs.rmSync(extDir, {recursive: true, force: true});
+  });
+
+  /**
+   * Every `prop: value` a generated stylesheet actually applies. Header
+   * comments and scope wrappers are ignored — two themes never share those.
+   */
+  function declarations(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => /^[-a-z][^{}]*:.+;$/.test(l)),
+    );
+  }
+  /** Every component rule a stylesheet opens, e.g. `.astryx-switch {`. */
+  function selectors(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.endsWith('{') && l.startsWith('.')),
+    );
+  }
+
+  /** A base theme with geometry, elevation and a component override. */
+  const BASE_SOURCE = `export const brandTheme = {
+    name: 'ext-base',
+    tokens: {
+      '--radius-element': '6px',
+      '--shadow-low': '0 1px 3px rgb(0 0 0 / 0.1)',
+      '--color-border-emphasized': '#D4D4D4',
+    },
+    components: {
+      switch: {base: {backgroundColor: 'var(--color-border-emphasized)'}},
+    },
+  };\n`;
+
+  /**
+   * The child names its base with a plain relative specifier, exactly as a
+   * generated palette does. `theme build` writes `ext-base.js` next to
+   * `ext-base.mjs`, so `./ext-base` is ambiguous — and the artifact, which
+   * exports `extBaseTheme` rather than `brandTheme`, is the wrong answer.
+   */
+  const CHILD_SOURCE = `import {defineTheme} from '@astryxdesign/core/theme';
+  import {brandTheme} from './ext-base';
+  export const paletteTheme = defineTheme({
+    name: 'ext-child',
+    extends: brandTheme,
+    tokens: {'--color-accent': 'hsl(220 88% 72%)'},
+  });\n`;
+
+  it('emits every declaration its base emits (the child stylesheet is self-contained)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    // Build the base FIRST, as any real project does — that write is what
+    // used to poison the child's build.
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    const baseCss = fs.readFileSync(path.join(extDir, 'ext-base.css'), 'utf8');
+    const childCss = fs.readFileSync(
+      path.join(extDir, 'ext-child.css'),
+      'utf8',
+    );
+
+    const childDecls = declarations(childCss);
+    expect([...declarations(baseCss)].filter(d => !childDecls.has(d))).toEqual(
+      [],
+    );
+
+    const childSelectors = selectors(childCss);
+    expect([...selectors(baseCss)].filter(s => !childSelectors.has(s))).toEqual(
+      [],
+    );
+
+    // …and the child's own override still wins.
+    expect(childCss).toContain('--color-accent: hsl(220 88% 72%);');
+  });
+
+  it('resolves the base from its source, not from the generated sibling artifact', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    const result = await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    expect(result?.data.componentCount).toBe(1);
+    expect(result?.data.tokenCount).toBe(4);
+  });
+
+  it('inherits component overrides when the base IS a built theme module', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+
+    // Extending a package's pre-built theme module (e.g. the `./built`
+    // subpath the shipped themes expose) must not silently drop its
+    // component overrides.
+    fs.writeFileSync(
+      path.join(extDir, 'ext-built-child.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {extBaseTheme} from './ext-base.js';
+      export const builtChildTheme = defineTheme({
+        name: 'ext-built-child',
+        extends: extBaseTheme,
+      });\n`,
+    );
+
+    await themeBuild('ext-built-child.mjs', {}, {cwd: extDir});
+    const css = fs.readFileSync(
+      path.join(extDir, 'ext-built-child.css'),
+      'utf8',
+    );
+
+    expect(css).toContain('.astryx-switch {');
+    expect(css).toContain('--radius-element: 6px;');
+  });
+
+  it('resolves extends on a plain object theme file (no defineTheme call)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(
+      path.join(extDir, 'ext-plain.mjs'),
+      `import {brandTheme} from './ext-base.mjs';
+      export default {
+        name: 'ext-plain',
+        extends: brandTheme,
+        tokens: {'--color-accent': '#ff0000'},
+      };\n`,
+    );
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-plain.mjs', {}, {cwd: extDir});
+
+    const css = fs.readFileSync(path.join(extDir, 'ext-plain.css'), 'utf8');
+    expect(css).toContain('--radius-element: 6px;');
+    expect(css).toContain('.astryx-switch {');
+  });
+
+  it('fails loudly when the base import resolved to nothing', async () => {
+    fs.writeFileSync(
+      path.join(extDir, 'ext-broken.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {notAThing} from './ext-missing.mjs';
+      export const brokenTheme = defineTheme({
+        name: 'ext-broken',
+        extends: notAThing,
+        tokens: {'--color-accent': '#ff0000'},
+      });\n`,
+    );
+    fs.writeFileSync(
+      path.join(extDir, 'ext-missing.mjs'),
+      `export const somethingElse = 1;\n`,
+    );
+
+    await expect(
+      themeBuild('ext-broken.mjs', {}, {cwd: extDir}),
+    ).rejects.toThrow(/extends/);
   });
 });

package/assets/docs/theme.doc.mjs

@@ -253,10 +253,15 @@ const brandTheme = defineTheme({
             ['tokens', 'Base tokens are copied first, then child tokens override on top.'],
             ['components', 'Deep-merged: child component rules override matching keys from the base.'],
             ['icons', 'Shallow-merged: child icons override matching names from the base.'],
-            ['fonts', 'Base fonts included first, then child fonts appended.'],
+            ['indicators', 'Shallow-merged: child indicators override matching names from the base.'],
+            ['onDark, onLight', "Deep-merged per surface: the base's resolved surface first, then the child's overrides."],
             ['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],
           ],
         },
+        {
+          type: 'prose',
+          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme — most often an import that missed — is a build error rather than a theme that silently inherits nothing.',
+        },
       ],
     },
     {

package/foundation/fs/path-safety.mjs

@@ -154,9 +154,9 @@ export function sanitizeName(name, options = {}) {
     );
   }
 
-  if (name === '.' || name === '..' || name.startsWith('..')) {
+  if (name === '.' || name === '..' || name.startsWith('.')) {
     throw new PathSafetyError(
-      `Invalid ${label} "${name}": must not be '.' or start with '..'.`,
+      `Invalid ${label} "${name}": must not start with '.'.`,
       'NAME_TRAVERSAL',
     );
   }

package/foundation/fs/path-safety.test.mjs

@@ -91,6 +91,13 @@ describe('sanitizeName', () => {
     expect(() => sanitizeName('.')).toThrow(PathSafetyError);
   });
 
+  it('rejects dotfile names (.env, .htaccess) that could create hidden files', () => {
+    expect(() => sanitizeName('.env')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.htaccess')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.bashrc')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.gitignore')).toThrow(PathSafetyError);
+  });
+
   it('rejects NUL bytes', () => {
     expect(() => sanitizeName('foo\0bar')).toThrow(PathSafetyError);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.2-canary.b2057d1",
+  "version": "0.4.2-canary.bb07062",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.4.2-canary.b2057d1",
-    "@astryxdesign/core": "0.4.2-canary.b2057d1",
-    "@astryxdesign/lab": "0.4.2-canary.b2057d1",
-    "@astryxdesign/theme-neutral": "0.4.2-canary.b2057d1",
+    "@astryxdesign/charts": "0.4.2-canary.bb07062",
+    "@astryxdesign/core": "0.4.2-canary.bb07062",
+    "@astryxdesign/lab": "0.4.2-canary.bb07062",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.bb07062",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.4.2-canary.b2057d1",
-    "@astryxdesign/core": "0.4.2-canary.b2057d1",
-    "@astryxdesign/lab": "0.4.2-canary.b2057d1",
-    "@astryxdesign/theme-neutral": "0.4.2-canary.b2057d1",
+    "@astryxdesign/charts": "0.4.2-canary.bb07062",
+    "@astryxdesign/core": "0.4.2-canary.bb07062",
+    "@astryxdesign/lab": "0.4.2-canary.bb07062",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.bb07062",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {