@astryxdesign/cli 0.1.8-canary.3cbbe66 → 0.1.8-canary.433a57e

package/bin/astryx.mjs

@@ -13,22 +13,21 @@
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
 //
-// Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
-// path. When the CLI is installed as a package, `npx astryx` runs this file
-// through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
-// relative specifiers from the symlink's directory rather than the real package
-// — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
-// realpath-ing `import.meta.url` makes these imports resolve correctly however
-// the bin is invoked (symlink, copy, or Windows shim). Uses only built-ins, so
-// the version gate below still runs first.
+// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
+// installed as a package, `npx astryx` runs this file through the
+// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
+// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
+// than the real package — breaking bare `../src/...` imports with a cryptic
+// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
+// resolve correctly however the bin is invoked (symlink, copy, or Windows
+// shim). Uses only built-ins, so the version gate below still runs first.
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {realpathSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 
 const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
-/** @param {string} rel */
 const importSrc = rel =>
-  import(pathToFileURL(join(binDir, '..', rel)).href);
+  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
 
 const {isNodeVersionSupported, unsupportedNodeMessage} =
   await importSrc('lib/node-version.mjs');
@@ -55,7 +54,7 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await importSrc('cli/index.mjs');
+const {program} = await importSrc('index.mjs');
 const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
 const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
@@ -73,7 +72,6 @@ function inJsonMode() {
   return isJsonMode() || process.argv.slice(2).includes('--json');
 }
 
-/** @param {unknown} err */
 function handleFatal(err) {
   // CommanderError (parse errors, --help, unknown command) routes
   // through the JSON shim so that a --json consumer always gets a

package/docs/internationalization.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   title: 'Internationalization',
   category: 'guide',
   description:
-    'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
+    'Localize astryx component strings, provide translation catalogs, override default text, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
 
   sections: [
     {
@@ -16,13 +16,13 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',
+          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale`, and astryx components pick up localized strings automatically.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Wrap your app',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
 
 function App() {
   return (
@@ -32,56 +32,53 @@ function App() {
   );
 }`,
         },
-        {
-          type: 'prose',
-          text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',
-        },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Load an astryx locale catalog',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import fr from '@astryxdesign/core/locales/fr.json';
+          label: 'Read strings inside a component',
+          code: `import {useTranslator} from '@astryxdesign/core';
 
-<InternationalizationProvider locale="fr" messages={{fr}}>
-  <App />
-</InternationalizationProvider>;`,
+function SaveButton() {
+  const t = useTranslator();
+  return <button>{t('@myapp.actions.save')}</button>;
+}`,
         },
         {
           type: 'prose',
-          text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
+          text: 'The hook is available to consumer components too, but using it is entirely optional: many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement; the resolver treats every key as an opaque string.',
         },
         {
           type: 'prose',
-          text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',
+          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
         },
       ],
     },
     {
-      title: 'Runtime language swap',
+      title: 'Providing locale catalogs',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
+          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work: the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
         },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Toggle between locales',
-          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
+          label: 'Add French',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+import fr from './locales/astryx/fr.json';
 
-<InternationalizationProvider locale={locale} messages={{fr}}>
-  <Button
-    label={locale === 'en' ? 'Français' : 'English'}
-    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
-  />
+<InternationalizationProvider locale="fr" messages={{fr}}>
   <App />
 </InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
+          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point: every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
+        },
+        {
+          type: 'prose',
+          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Translations are coordinated through Crowdin — contribute at https://crowdin.com/project/astryx.',
         },
       ],
     },
@@ -122,7 +119,7 @@ import fr from '@astryxdesign/core/locales/fr.json';
           type: 'code',
           lang: 'tsx',
           label: 'Astryx + react-intl side by side',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
 import {Selector} from '@astryxdesign/core/Selector';
 import {Button} from '@astryxdesign/core/Button';
 import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
@@ -172,56 +169,35 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",
+          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
         },
       ],
     },
     {
-      title: 'Using astryx as your i18n library',
+      title: 'Runtime language swap',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",
+          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
         },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Translate app strings with astryx',
-          code: `import {Button} from '@astryxdesign/core/Button';
-import {
-  InternationalizationProvider,
-  useTranslator,
-  type Catalog,
-  type MessagesByLocale,
-} from '@astryxdesign/core/i18n';
-
-const en: Catalog = {
-  '@myapp.actions.save': {defaultMessage: 'Save'},
-};
-
-const fr: Catalog = {
-  '@myapp.actions.save': {defaultMessage: 'Enregistrer'},
-};
-
-const messages: MessagesByLocale = {en, fr};
-
-function SaveButton() {
-  const t = useTranslator();
-  return <Button label={t('@myapp.actions.save')} />;
-}
+          label: 'Toggle between locales',
+          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
 
-export default function App() {
-  return (
-    <InternationalizationProvider locale="fr" messages={messages}>
-      <SaveButton />
-    </InternationalizationProvider>
-  );
-}`,
+<InternationalizationProvider locale={locale} messages={{fr}}>
+  <Button
+    label={locale === 'en' ? 'Français' : 'English'}
+    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
+  />
+  <App />
+</InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',
+          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
         },
       ],
     },
@@ -231,57 +207,39 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switching to it in development instantly reveals any astryx string that isn\'t going through the translator, plus any layout that breaks under longer text.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Turn on pseudo-localization',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import pseudo from '@astryxdesign/core/locales/pseudo.json';
+          code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
 
 <InternationalizationProvider locale="pseudo" messages={{pseudo}}>
   <App />
 </InternationalizationProvider>;`,
         },
+        {
+          type: 'prose',
+          text: 'Any bare English text you still see on screen is a hardcoded string that needs to be routed through `useTranslator`.',
+        },
+        {
+          type: 'prose',
+          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated; anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
+        },
       ],
     },
     {
       title: 'For contributors',
       category: 'guide',
       content: [
-        {
-          type: 'heading',
-          level: 3,
-          text: 'Developers',
-        },
-        {
-          type: 'prose',
-          text: 'Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Read an astryx string',
-          code: `import {useTranslator} from '@astryxdesign/core/i18n';
-
-function SaveButton() {
-  const t = useTranslator();
-  return <button>{t('@astryx.actions.save')}</button>;
-}`,
-        },
         {
           type: 'prose',
           text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
         },
-        {
-          type: 'heading',
-          level: 3,
-          text: 'Translators',
-        },
         {
           type: 'prose',
-          text: 'Crowdin is the preferred way to contribute — [join a language](https://crowdin.com/project/astryx), translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
+          text: 'Translators: Crowdin is the preferred way to contribute — join a language at https://crowdin.com/project/astryx, translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.8-canary.3cbbe66",
+  "version": "0.1.8-canary.433a57e",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -32,48 +32,41 @@
   "exports": {
     ".": "./bin/astryx.mjs",
     "./json": {
-      "types": "./types/index.d.ts",
-      "import": "./lib/parse.mjs"
+      "types": "./src/types/index.d.ts",
+      "import": "./src/lib/parse.mjs"
     },
     "./api": {
-      "types": "./types/api.d.ts",
-      "import": "./api/index.mjs"
+      "types": "./src/types/api.d.ts",
+      "import": "./src/api/index.mjs"
     },
     "./config": {
-      "types": "./types/config.d.ts",
-      "import": "./authoring/config.mjs"
+      "types": "./src/types/config.d.ts",
+      "import": "./src/config.mjs"
     },
     "./integration": {
-      "types": "./types/integration.d.ts",
-      "import": "./authoring/integration.mjs"
+      "types": "./src/types/integration.d.ts",
+      "import": "./src/integration.mjs"
     },
     "./doc": {
-      "types": "./types/doc.d.ts",
-      "import": "./authoring/doc.mjs"
+      "types": "./src/types/doc.d.ts",
+      "import": "./src/doc.mjs"
     },
     "./template": {
-      "types": "./types/template-api.d.ts",
-      "import": "./authoring/template.mjs"
+      "types": "./src/types/template-api.d.ts",
+      "import": "./src/template.mjs"
     },
     "./codemod": {
-      "types": "./types/codemod.d.ts",
-      "import": "./authoring/codemod.mjs"
+      "types": "./src/types/codemod.d.ts",
+      "import": "./src/codemod.mjs"
     },
     "./xle": {
-      "types": "./lib/xle/browser.d.ts",
-      "import": "./lib/xle/browser.mjs"
+      "types": "./src/lib/xle/browser.d.ts",
+      "import": "./src/lib/xle/browser.mjs"
     }
   },
   "files": [
     "bin",
-    "api",
-    "cli",
-    "codemods",
-    "authoring",
-    "lib",
-    "utils",
-    "types",
-    "schemas",
+    "src",
     "scripts/postinstall.mjs",
     "templates",
     "docs",
@@ -86,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/core": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/lab": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.3cbbe66",
+    "@astryxdesign/charts": "0.1.8-canary.433a57e",
+    "@astryxdesign/core": "0.1.8-canary.433a57e",
+    "@astryxdesign/lab": "0.1.8-canary.433a57e",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.433a57e",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -107,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/core": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/lab": "0.1.8-canary.3cbbe66",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.3cbbe66",
+    "@astryxdesign/charts": "0.1.8-canary.433a57e",
+    "@astryxdesign/core": "0.1.8-canary.433a57e",
+    "@astryxdesign/lab": "0.1.8-canary.433a57e",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.433a57e",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/scripts/postinstall.mjs

@@ -24,11 +24,11 @@ const HERE = fileURLToPath(import.meta.url);
  * Pure decision: should the postinstall print the setup nudge? Split out so the
  * matrix is unit-testable without an actual npm install.
  *
- * @param {object} [opts]
- * @param {string} [opts.scriptPath] - Absolute path of this script (location tells
+ * @param {object} opts
+ * @param {string} opts.scriptPath - Absolute path of this script (location tells
  *   us dependency vs monorepo vs npx-cache).
  * @param {string} [opts.npmCommand] - process.env.npm_command ('install', 'exec', …).
- * @param {boolean} [opts.isSetUp] - Whether the project already ran init.
+ * @param {boolean} opts.isSetUp - Whether the project already ran init.
  * @returns {boolean}
  */
 export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
@@ -41,7 +41,7 @@ export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
 /** @param {string} root @returns {Promise<boolean>} */
 async function projectIsSetUp(root) {
   try {
-    const {isAstryxInitialized} = await import('../cli/commands/agent-docs.mjs');
+    const {isAstryxInitialized} = await import('../src/commands/agent-docs.mjs');
     return isAstryxInitialized(root);
   } catch {
     return false; // best-effort — if the check can't load, fall through and nudge

package/{api/blog → src/api}/blog.mjs

@@ -10,9 +10,9 @@
  * blog's structure can change freely without touching the CLI.
  */
 
-import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;
@@ -20,10 +20,6 @@ const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
 
 const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
 
-/**
- * @param {string} url
- * @returns {Promise<string>}
- */
 async function fetchText(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -35,12 +31,7 @@ async function fetchText(url) {
     });
   } catch (e) {
     clearTimeout(timer);
-    const reason =
-      e instanceof Error
-        ? e.name === 'AbortError'
-          ? 'timed out'
-          : e.message
-        : String(e);
+    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
     throw new AstryxError(
       `Could not reach ${url}: ${reason}`,
       [],
@@ -70,7 +61,6 @@ async function fetchText(url) {
  * Defense in depth: a post's plaintext URL comes from feed content. Require it
  * to live on the canonical origin so even a tampered feed can't redirect the
  * CLI to another host.
- * @param {string} target
  */
 function assertCanonicalOrigin(target) {
   let targetOrigin;
@@ -92,10 +82,6 @@ function assertCanonicalOrigin(target) {
   }
 }
 
-/**
- * @param {string} value
- * @returns {string}
- */
 function unescapeXml(value) {
   return value
     .replace(/&lt;/g, '<')
@@ -105,23 +91,12 @@ function unescapeXml(value) {
     .replace(/&amp;/g, '&');
 }
 
-/**
- * @param {string} item
- * @param {string} name
- * @returns {string}
- */
 function tag(item, name) {
   const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
   return m ? unescapeXml(m[1].trim()) : '';
 }
 
-/**
- * @param {string} item
- * @param {string} name
- * @returns {string[]}
- */
 function tagAll(item, name) {
-  /** @type {string[]} */
   const out = [];
   const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
   let m;
@@ -129,11 +104,7 @@ function tagAll(item, name) {
   return out;
 }
 
-/**
- * Extract the plaintext alternate href from an <item>.
- * @param {string} item
- * @returns {string | null}
- */
+/** Extract the plaintext alternate href from an <item>. */
 function textHref(item) {
   // Match the atom:link alternate regardless of attribute order/quoting; then
   // confirm it's the text/plain alternate before trusting the href.
@@ -150,11 +121,7 @@ function textHref(item) {
   return null;
 }
 
-/**
- * Derive a slug from a post link (last path segment).
- * @param {string} link
- * @returns {string}
- */
+/** Derive a slug from a post link (last path segment). */
 function slugFromLink(link) {
   try {
     const path = new URL(link).pathname.replace(/\/$/, '');
@@ -164,9 +131,6 @@ function slugFromLink(link) {
   }
 }
 
-/**
- * @param {string} xml
- */
 function parseFeed(xml) {
   const items = [];
   const re = /<item>([\s\S]*?)<\/item>/g;

package/{api/blog → src/api}/blog.test.mjs

@@ -9,8 +9,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {blog} from './blog.mjs';
-import {AstryxError} from '../error.mjs';
-import {SITE_URL} from '../../lib/site.mjs';
+import {AstryxError} from './error.mjs';
+import {SITE_URL} from '../lib/site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">