An open source design system that's fully customizable and agent ready
TypeScript
refactor(cli): rename config file xds.config.mjs -> astryx.config.mjs (#3017)
EJ Hammond488eaf77138c
diff --git a/.changeset/astryx-config-file.md b/.changeset/astryx-config-file.mdnew file mode 100644index 0000000000..537554deea--- /dev/null+++ b/.changeset/astryx-config-file.md@@ -0,0 +1,11 @@+---+'@astryxdesign/cli': patch+---++[breaking] Read project config from `astryx.config.mjs` (was `xds.config.mjs`)+@ejhammond++The CLI now resolves its optional project config from `astryx.config.mjs`+instead of `xds.config.mjs` — a hard cut, no fallback. Consumers with an+`xds.config.mjs` must rename it to `astryx.config.mjs` (the config shape and+all fields are unchanged). Part of removing `xds` naming from the public API.diff --git a/apps/sandbox/.gitignore b/apps/sandbox/.gitignoreindex 2927789959..b111587c53 100644--- a/apps/sandbox/.gitignore+++ b/apps/sandbox/.gitignore@@ -2,7 +2,7 @@ node_modules# Auto-generated by `xds init --features agents` (postinstall)AGENTS.md-xds.config.mjs+astryx.config.mjs.claude/CLAUDE.md/pagesdiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 02e587abd9..01d9e6a7e2 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -155,7 +155,7 @@ if (isError(result)) {| `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). || `ERR_THEME_INVALID` | A theme definition was missing a required property (e.g. `name`). || `ERR_THEME_LOAD` | A theme file could not be loaded / parsed into a `defineTheme` result. |-| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `xds.config.mjs` (fetch-by-id). |+| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id). || `ERR_TEMPLATE_GET` | A configured `template.get` threw or returned an invalid value. || `ERR_VERSION_DETECT` | The current `@astryxdesign/core` version could not be detected. || `ERR_INVALID_VERSION` | A `--from`/`--to` value was not a valid semver string. |@@ -342,8 +342,8 @@ xds doctor — diagnosing your setup⚠ Theme packagesNo @astryxdesign/theme-* packages are installed.→ fix: Install a theme, e.g. `npm install @astryxdesign/theme-default`, then import its CSS or set xds.theme.- ℹ xds.config.mjs- No xds.config.mjs found — using defaults.+ ℹ astryx.config.mjs+ No astryx.config.mjs found — using defaults.ℹ AI agent docsNo agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.→ fix: Generate agent docs with `xds init --features agents`.@@ -365,7 +365,7 @@ No failures — but review the ⚠ warnings above when you can.| @astryxdesign/core installed | pass / fail | `@astryxdesign/core` is resolvable from the project || Version alignment | pass / warn / info | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli` || Theme packages | pass / warn | An `@astryxdesign/theme-*` package is installed and a theme is wired |-| xds.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |+| astryx.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape || AI agent docs | pass / warn / info | Agent docs exist and contain the XDS section markers || Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed || Package manager | info | Reports the detected package manager |@@ -385,7 +385,7 @@ data: { checks, summary } }`) that AI agents and scripts can parse.## Configuration-The CLI reads from an optional `xds.config.mjs` in your project root:+The CLI reads from an optional `astryx.config.mjs` in your project root:```javascriptexport default {diff --git a/packages/cli/src/api/doctor.mjs b/packages/cli/src/api/doctor.mjsindex f69b5fed44..933d2bd80b 100644--- a/packages/cli/src/api/doctor.mjs+++ b/packages/cli/src/api/doctor.mjs@@ -50,7 +50,7 @@ const _require = createRequire(import.meta.url);* @property {string} cwd - Directory to diagnose.* @property {string} nodeVersion - Running Node version.* @property {string|null} coreDir - Resolved @astryxdesign/core directory, or null.- * @property {string|null} configPath - Resolved xds.config.mjs path, or null.+ * @property {string|null} configPath - Resolved astryx.config.mjs path, or null.* @property {string|null} configTheme - theme value read from config, or null.*/@@ -251,11 +251,11 @@ export function checkThemes(ctx) {label: 'Theme packages',status: 'warn',message: `Theme package(s) installed (${names}) but no theme appears wired.`,- fix: 'Wire a theme via the `astryx.theme` field in package.json, the ASTRYX_THEME env var, or your xds.config.mjs.',+ fix: 'Wire a theme via the `astryx.theme` field in package.json, the ASTRYX_THEME env var, or your astryx.config.mjs.',};}- const source = hasConfigTheme ? 'xds.config.mjs theme' : wiring.source;+ const source = hasConfigTheme ? 'astryx.config.mjs theme' : wiring.source;return {id: 'themes',label: 'Theme packages',@@ -265,7 +265,7 @@ export function checkThemes(ctx) {}/**- * Check 5 — xds.config.mjs (if present) loads and has a valid shape.+ * Check 5 — astryx.config.mjs (if present) loads and has a valid shape.* @param {DoctorContext} ctx* @returns {Promise<DoctorCheck>}*/@@ -273,9 +273,9 @@ export async function checkConfig(ctx) {if (!ctx.configPath) {return {id: 'config',- label: 'xds.config.mjs',+ label: 'astryx.config.mjs',status: 'info',- message: 'No xds.config.mjs found — using defaults.',+ message: 'No astryx.config.mjs found — using defaults.',};}@@ -288,10 +288,10 @@ export async function checkConfig(ctx) {if (config !== undefined && (typeof config !== 'object' || config === null)) {return {id: 'config',- label: 'xds.config.mjs',+ label: 'astryx.config.mjs',status: 'fail',- message: `xds.config.mjs default export is not an object (got ${typeof config}).`,- fix: 'Export a default object from xds.config.mjs, e.g. `export default { theme: "default" };`.',+ message: `astryx.config.mjs default export is not an object (got ${typeof config}).`,+ fix: 'Export a default object from astryx.config.mjs, e.g. `export default { theme: "default" };`.',};}// Validate that `packages`, if present, is a string or array of strings.@@ -303,26 +303,26 @@ export async function checkConfig(ctx) {if (bad) {return {id: 'config',- label: 'xds.config.mjs',+ label: 'astryx.config.mjs',status: 'fail',- message: 'xds.config.mjs `packages` must be a string or array of strings.',+ message: 'astryx.config.mjs `packages` must be a string or array of strings.',fix: 'Set `packages` to a path string or array of path strings.',};}}return {id: 'config',- label: 'xds.config.mjs',+ label: 'astryx.config.mjs',status: 'pass',- message: `xds.config.mjs loaded cleanly (${path.relative(ctx.cwd, ctx.configPath) || ctx.configPath}).`,+ message: `astryx.config.mjs loaded cleanly (${path.relative(ctx.cwd, ctx.configPath) || ctx.configPath}).`,};} catch (err) {return {id: 'config',- label: 'xds.config.mjs',+ label: 'astryx.config.mjs',status: 'fail',- message: `xds.config.mjs failed to load: ${err.message}`,- fix: 'Fix the syntax/runtime error in xds.config.mjs so it imports cleanly.',+ message: `astryx.config.mjs failed to load: ${err.message}`,+ fix: 'Fix the syntax/runtime error in astryx.config.mjs so it imports cleanly.',};}}diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjsindex e0932df731..b533c9600c 100644--- a/packages/cli/src/api/template.mjs+++ b/packages/cli/src/api/template.mjs@@ -377,7 +377,7 @@ function extractSkeleton(source) {}/**- * Fetch a template by ID using the `template.get` hook in xds.config.mjs.+ * Fetch a template by ID using the `template.get` hook in astryx.config.mjs.* @param {string} id* @param {object} [options]* @param {string} [options.cwd]@@ -391,7 +391,7 @@ export async function getTemplateById(id, options = {}) {if (typeof getter !== 'function') {throw new AstryxError('Template fetching by ID is not configured.\n' +- 'Add a template.get function to xds.config.mjs:\n\n' ++ 'Add a template.get function to astryx.config.mjs:\n\n' +' export default {\n' +' template: {\n' +" get: async (id) => { /* return template source string */ },\n" +diff --git a/packages/cli/src/commands/discover.mjs b/packages/cli/src/commands/discover.mjsindex ae2bcf0a22..2fd22365eb 100644--- a/packages/cli/src/commands/discover.mjs+++ b/packages/cli/src/commands/discover.mjs@@ -50,7 +50,7 @@ export function registerDiscover(program) {if (config.packages.length === 0) {humanLog('No package directories configured.');humanLog('');- humanLog('Add a packages field to xds.config.mjs:');+ humanLog('Add a packages field to astryx.config.mjs:');humanLog('');humanLog(' export default {');humanLog(" packages: ['/path/to/your/libs'],");diff --git a/packages/cli/src/commands/doctor.test.mjs b/packages/cli/src/commands/doctor.test.mjsindex 09d08e7917..8e746dd8ef 100644--- a/packages/cli/src/commands/doctor.test.mjs+++ b/packages/cli/src/commands/doctor.test.mjs@@ -118,19 +118,19 @@ describe('doctor — individual checks', () => {expect(res.status).toBe('pass');});- it('config: INFO when no xds.config.mjs', async () => {+ it('config: INFO when no astryx.config.mjs', async () => {const res = await checkConfig({cwd: tmpDir, configPath: null});expect(res.status).toBe('info');});- it('config: PASS when a valid xds.config.mjs loads', async () => {+ it('config: PASS when a valid astryx.config.mjs loads', async () => {// Vitest intercepts dynamic import() through Vite's resolver, which can't// serve a file written to an arbitrary tmp path at runtime. Write the// fixture inside the package tree so Vite can resolve it, then clean up.const fixtureDir = fs.mkdtempSync(path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),);- const configPath = path.join(fixtureDir, 'xds.config.mjs');+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');try {fs.writeFileSync(configPath, 'export default { theme: "default" };');const res = await checkConfig({cwd: fixtureDir, configPath});@@ -143,11 +143,11 @@ describe('doctor — individual checks', () => {}});- it('config: FAIL when xds.config.mjs throws on import', async () => {+ it('config: FAIL when astryx.config.mjs throws on import', async () => {const fixtureDir = fs.mkdtempSync(path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),);- const configPath = path.join(fixtureDir, 'xds.config.mjs');+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');try {fs.writeFileSync(configPath, 'throw new Error("boom");\nexport default {};');const res = await checkConfig({cwd: fixtureDir, configPath});@@ -162,7 +162,7 @@ describe('doctor — individual checks', () => {const fixtureDir = fs.mkdtempSync(path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),);- const configPath = path.join(fixtureDir, 'xds.config.mjs');+ const configPath = path.join(fixtureDir, 'astryx.config.mjs');try {fs.writeFileSync(configPath, 'export default { packages: [123] };');const res = await checkConfig({cwd: fixtureDir, configPath});diff --git a/packages/cli/src/commands/gap-report.mjs b/packages/cli/src/commands/gap-report.mjsindex 8d3fe02b2b..53488cd6cd 100644--- a/packages/cli/src/commands/gap-report.mjs+++ b/packages/cli/src/commands/gap-report.mjs@@ -81,11 +81,11 @@ function isCancel(value) {}/**- * Update or insert the gapReport key in xds.config.mjs.+ * Update or insert the gapReport key in astryx.config.mjs.* Preserves existing keys (e.g. theme).*/function writeGapReportConfig(targetDir, gapReportValue) {- const configPath = path.join(targetDir, 'xds.config.mjs');+ const configPath = path.join(targetDir, 'astryx.config.mjs');if (fs.existsSync(configPath)) {let content = fs.readFileSync(configPath, 'utf-8');@@ -193,7 +193,7 @@ export function registerGapReport(program) {);} else {// GitHub mode — remove gapReport key or set to default- const configPath = path.join(targetDir, 'xds.config.mjs');+ const configPath = path.join(targetDir, 'astryx.config.mjs');if (fs.existsSync(configPath)) {let content = fs.readFileSync(configPath, 'utf-8');// Remove the gapReport line entirely to use default@@ -216,7 +216,7 @@ export function registerGapReport(program) {}}- p.outro('Configuration saved to xds.config.mjs');+ p.outro('Configuration saved to astryx.config.mjs');});// --- main gap-report command ---@@ -256,7 +256,7 @@ export function registerGapReport(program) {if (!config.enabled) {if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);humanLog(- `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or xds.config.mjs).\n` ++ `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +`Run \`${getRunPrefix()} xds gap-report setup\` to configure.`,);return;diff --git a/packages/cli/src/commands/json-contract.test.mjs b/packages/cli/src/commands/json-contract.test.mjsindex 79495ef976..8666bc9d61 100644--- a/packages/cli/src/commands/json-contract.test.mjs+++ b/packages/cli/src/commands/json-contract.test.mjs@@ -96,8 +96,8 @@ describe('--json contract: rejects before side effects', () => {expect(status).toBe(1);const parsed = parseJson(stdout);expect(parsed.error).toMatch(/gap-report setup/);- // No xds.config.mjs written.- expect(fs.existsSync(path.join(tmpDir, 'xds.config.mjs'))).toBe(false);+ // No astryx.config.mjs written.+ expect(fs.existsSync(path.join(tmpDir, 'astryx.config.mjs'))).toBe(false);});it('xds theme --json (parent, no subcommand) rejects without printing help', () => {@@ -157,7 +157,7 @@ describe('--json contract: supported commands emit valid envelopes', () => {// Configure gap-report so it doesn't error on "disabled" — we want to// hit the "interactive prompt would start" branch.fs.writeFileSync(- path.join(tmpDir, 'xds.config.mjs'),+ path.join(tmpDir, 'astryx.config.mjs'),'export default { gapReport: { command: "true" } };\n',);const {status, stdout} = runCli(['gap-report', '--json'], {cwd: tmpDir});diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjsindex 12e7a794ca..bb00a6042c 100644--- a/packages/cli/src/commands/template.mjs+++ b/packages/cli/src/commands/template.mjs@@ -134,7 +134,7 @@ export function registerTemplate(program) {templateCmd.command('get')- .description('Fetch a template by ID via the xds.config.mjs hook')+ .description('Fetch a template by ID via the astryx.config.mjs hook').requiredOption('--id <id>', 'Template identifier to fetch').action(async (options) => {const json = program.opts().json || false;diff --git a/packages/cli/src/lib/config.mjs b/packages/cli/src/lib/config.mjsindex 26b04e2283..aee88d5a76 100644--- a/packages/cli/src/lib/config.mjs+++ b/packages/cli/src/lib/config.mjs@@ -1,9 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Config loader — reads xds.config.mjs from project root+ * @file Config loader — reads astryx.config.mjs from project root*- * Walks up from cwd looking for xds.config.mjs.+ * Walks up from cwd looking for astryx.config.mjs.* Returns the config object or defaults if not found.*/@@ -16,13 +16,13 @@ const DEFAULTS = {};/**- * Find xds.config.mjs by walking up from startDir.+ * Find astryx.config.mjs by walking up from startDir.* Returns the absolute path or null.*/export function findConfigPath(startDir = process.cwd()) {let dir = startDir;for (let i = 0; i < 10; i++) {- const candidate = path.join(dir, 'xds.config.mjs');+ const candidate = path.join(dir, 'astryx.config.mjs');if (fs.existsSync(candidate)) return candidate;const parent = path.dirname(dir);if (parent === dir) break;@@ -32,7 +32,7 @@ export function findConfigPath(startDir = process.cwd()) {}/**- * Load and return the config from xds.config.mjs.+ * Load and return the config from astryx.config.mjs.* Returns defaults if no config file is found.*/export async function loadConfig(startDir = process.cwd()) {diff --git a/packages/cli/src/lib/error-codes.mjs b/packages/cli/src/lib/error-codes.mjsindex 2455e251f1..ff0d5b20c4 100644--- a/packages/cli/src/lib/error-codes.mjs+++ b/packages/cli/src/lib/error-codes.mjs@@ -159,7 +159,7 @@ export const ERROR_CODES = Object.freeze({ERR_THEME_LOAD: 'ERR_THEME_LOAD',// ── Template config ──────────────────────────────────────────────- /** `template.get` is not configured in xds.config.mjs (fetch-by-id). */+ /** `template.get` is not configured in astryx.config.mjs (fetch-by-id). */ERR_TEMPLATE_CONFIG: 'ERR_TEMPLATE_CONFIG',/** A configured `template.get` threw or returned an invalid value. */ERR_TEMPLATE_GET: 'ERR_TEMPLATE_GET',diff --git a/packages/cli/src/utils/github.mjs b/packages/cli/src/utils/github.mjsindex f108a4e367..57db45aa11 100644--- a/packages/cli/src/utils/github.mjs+++ b/packages/cli/src/utils/github.mjs@@ -6,7 +6,7 @@* Shared helpers for interacting with the GitHub CLI (`gh`).* Used by gap-report and swizzle commands.*- * Gap reporting can be configured via xds.config.mjs:+ * Gap reporting can be configured via astryx.config.mjs:* gapReport: false — disable entirely* gapReport: { command: './scripts/report-gap.sh' } — run custom script (receives JSON on stdin)*@@ -37,7 +37,7 @@ export const GAP_CATEGORIES = [/*** Load gap report configuration.*- * Priority: env var > xds.config.mjs > default (GitHub issue)+ * Priority: env var > astryx.config.mjs > default (GitHub issue)** Returns { enabled: boolean, command?: string }* - enabled: false → gap reporting disabled@@ -55,8 +55,8 @@ export function loadGapReportConfig() {return {enabled: true, command: envVar};}- // 2. Check xds.config.mjs- const configPath = path.join(process.cwd(), 'xds.config.mjs');+ // 2. Check astryx.config.mjs+ const configPath = path.join(process.cwd(), 'astryx.config.mjs');if (fs.existsSync(configPath)) {try {const content = fs.readFileSync(configPath, 'utf-8');