@astryxdesign/cli 0.1.7-canary.eb8e07b → 0.1.7

package/README.md

@@ -423,103 +423,13 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 
 ## Configuration
 
-The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
-(a sibling of `package.json`). Every field is optional; with no config file the
-CLI runs on defaults.
+The CLI reads from an optional `astryx.config.mjs` in your project root:
 
-```typescript
-import {createConfig} from '@astryxdesign/core/config';
-
-export default createConfig({
-  integrations: ['@acme/astryx-widgets'],
+```javascript
+export default {
+  templates: {
+    get: async id => fetchTemplateFromAPI(id),
+  },
   issuesUrl: 'https://github.com/your-org/your-repo/issues',
-});
-```
-
-`createConfig` is a type-preserving helper: it returns its argument unchanged
-and exists only to give the config file editor autocomplete and type-checking. A
-plain `export default {}` object works identically. It's exported from
-`@astryxdesign/core` (not the CLI) so your config file gets type feedback
-without depending on the CLI; the same helper is re-exported from
-`@astryxdesign/cli/config` for back-compat.
-
-| Field                         | Type                           | Purpose                                                                                         |
-| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
-| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
-
-The config is validated against a strict schema when the CLI loads it, so an
-unknown field is a hard error rather than a silent no-op. `astryx doctor`
-reports whether the config loads cleanly.
-
-## Integrations
-
-An **integration** is any npm package that contributes its own components,
-templates, and upgrade codemods to Astryx. The CLI surfaces them next to core's,
-through the same commands, so a consumer can `astryx component`,
-`astryx template`, and `astryx upgrade` across core and every integration
-uniformly. Use it to ship a first-party add-on, publish a third-party component
-library, or share an internal design-system package across apps.
-
-The system runs on two files, each with a small typed API:
-
-| File                             | Written by | Role                                      |
-| -------------------------------- | ---------- | ----------------------------------------- |
-| `astryx.config.{ts,mjs,js}`      | Consumer   | Lists which integration packages to load. |
-| `astryx.integration.{ts,mjs,js}` | Author     | Declares what a package contributes.      |
-
-The consumer side is the `integrations` field of [`astryx.config`](#configuration).
-The author side is the integration manifest below.
-
-### The integration manifest
-
-A package becomes an integration by exporting a manifest from
-`astryx.integration.{ts,mjs,js}` at its root (a sibling of `package.json`). The
-manifest points at where each kind of contribution lives; identity (name,
-version) comes from `package.json`, not the manifest.
-
-```typescript
-import {createIntegration} from '@astryxdesign/core/authoring';
-
-export default createIntegration({
-  components: './components',
-  templates: './templates',
-  codemods: './codemods',
-  issuesUrl: 'https://github.com/acme/widgets/issues',
-});
-```
-
-| Field        | Type     | Purpose                                                               |
-| ------------ | -------- | --------------------------------------------------------------------- |
-| `components` | `string` | Directory holding the package's components and their `.doc.*` files.  |
-| `templates`  | `string` | Directory holding the package's page/block templates.                 |
-| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
-| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
-
-Every field is optional; declare only the roots the package ships.
-`createIntegration` is a type-preserving helper (editor autocomplete and
-type-checking); it lives in `@astryxdesign/core/authoring` and is re-exported
-from `@astryxdesign/cli/integration` for back-compat.
-
-### How it works
-
-Every command loads the consumer's `astryx.config`, resolves each listed
-integration's manifest from `node_modules`, and discovers its contributions.
-Everything is validated against one strict schema at the load boundary, so the
-CLI presents core and integration contributions through a single, uniform
-surface.
-
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
-`astryx validate-integration <package>` for a detailed report on one package, or
-`astryx doctor` for an overall health check.
-
-For the full authoring walkthrough (component doc format, template packaging
-and `exports` requirements, and codemod authoring), see the guide:
-
-```bash
-astryx docs cli-integrations
+};
 ```

package/docs/integration-authoring.md

@@ -0,0 +1,105 @@
+# Authoring an Astryx Integration
+
+> **Status:** working notes. This should eventually move to the public wiki
+> alongside the rest of the integration-authoring guidance; it lives here for
+> now so it ships and is versioned with the CLI.
+
+An **Integration** is an npm package that contributes components, templates, and/or
+codemods to a consumer's design-system workflow. Consumers install the 3rd party
+package, add a line to their astryx.config file:
+
+```js
+import {createConfig} from '@astryxdesign/cli/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
+  ...
+});
+```
+
+Then the integration's components and templates will be surfaced alongside Astryx
+components in the Astryx CLI.
+
+```sh
+astryx component AcmeCarousel --props
+astryx component --list --package @acme/astryx-widgets
+```
+
+## The Integration File
+
+In order to register your package as an Astryx Integration, create an
+`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
+tells Astryx where to find your components, templates, codemods, etc.
+
+```js
+// astryx.integration.{ts,mjs,js}
+import {createIntegration} from '@astryxdesign/cli/integration';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+## Components
+
+Your components themselves may be exported from your library as you see fit (consumers
+will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
+file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
+
+```js
+// AcmeCarousel.doc.ts
+import {createComponentDoc} from '@astryxdesign/cli/doc';
+
+export default createComponentDoc({
+  name: 'AcmeCarousel',
+  description: '...',
+  ...
+});
+```
+
+## Templates
+
+Templates are typically not exported from the package directly, but instead accessed
+via the Astryx CLI. Consumers can look through your templates and materialize them
+into their apps.
+
+You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
+(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
+
+```js
+// AcmeLandingPage.template.ts
+import {createPageTemplate} from '@astryxdesign/cli/template';
+
+export default createPageTemplate({
+  ...
+});
+```
+
+Note that, since the CLI needs access to the template source code, you need to make sure
+that it is included in your published package. This will also allow us to render previews
+of templates in the future by bundling your template into a doc site build.
+
+Typically, this is done via the package.json `exports` key.
+
+```jsonc
+{
+  "exports": {
+    // ...
+    "./templates/*.tsx": "./templates/*.tsx",
+  },
+}
+```
+
+In order to verify that it's working, you can test importing the template component like this:
+
+```ts
+import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
+```
+
+Import **with the `.tsx` extension** — an extensionless specifier won't resolve
+under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
+above is what lets that import type-check without consumers enabling
+`allowImportingTsExtensions`.

package/package.json

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

package/docs/cli-integrations.doc.mjs

@@ -1,150 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceDoc} */
-
-export const docs = {
-  name: 'cli-integrations',
-  title: 'CLI Integrations',
-  category: 'guide',
-  description:
-    'Author an npm package that contributes components, templates, and upgrade codemods to Astryx.',
-
-  sections: [
-    {
-      title: 'Overview',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'An integration is an npm package that contributes components, templates, and/or upgrade codemods to a consumer\u2019s design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration\u2019s contributions show up alongside core\u2019s in the same CLI commands.',
-        },
-        {
-          type: 'prose',
-          text: 'The system runs on two files. The consumer writes `astryx.config.{ts,mjs,js}` at their project root to list which packages to load. The author writes `astryx.integration.{ts,mjs,js}` at the package root to declare what the package contributes. This page is the author\u2019s guide. For the consumer side, run `npx astryx docs getting-started`.',
-        },
-        {
-          type: 'prose',
-          text: 'On the consumer side, adding your package is one line:',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "import {createConfig} from '@astryxdesign/core/config';\n\nexport default createConfig({\n  integrations: ['@acme/astryx-widgets'],\n});",
-        },
-        {
-          type: 'prose',
-          text: 'Your components and templates then appear next to core\u2019s:',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'astryx component --list --package @acme/astryx-widgets\nastryx component AcmeCarousel --props',
-        },
-      ],
-    },
-    {
-      title: 'The Integration File',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, and codemods. Identity (name, version) comes from your `package.json`, not this file.',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "// astryx.integration.ts\nimport {createIntegration} from '@astryxdesign/core/authoring';\n\nexport default createIntegration({\n  components: './components',\n  templates: './templates',\n  codemods: './codemods',\n  issuesUrl: 'https://github.com/acme/widgets/issues',\n});",
-        },
-        {
-          type: 'prose',
-          text: 'Every field is optional. Declare only the contribution roots your package ships. `createIntegration` is a type-preserving helper for editor autocomplete and type-checking. It lives in `@astryxdesign/core/authoring` and is also re-exported from `@astryxdesign/cli/integration` for back-compat.',
-        },
-      ],
-    },
-    {
-      title: 'Components',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "// AcmeCarousel.doc.ts\nimport {createComponentDoc} from '@astryxdesign/core/authoring';\n\nexport default createComponentDoc({\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n});",
-        },
-      ],
-    },
-    {
-      title: 'Templates',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template with `createPageTemplate` (full pages) or `createBlockTemplate` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "// AcmeLandingPage.template.ts\nimport {createPageTemplate} from '@astryxdesign/core/authoring';\n\nexport default createPageTemplate({\n  // name, description, preview, ...\n});",
-        },
-        {
-          type: 'prose',
-          text: 'The CLI needs the template source at consume time, so make sure it is included in your published package. This is typically done via the `exports` key in `package.json`. It also lets the docsite render template previews in the future.',
-        },
-        {
-          type: 'code',
-          lang: 'jsonc',
-          code: '{\n  "exports": {\n    // ...\n    "./templates/*.tsx": "./templates/*.tsx"\n  }\n}',
-        },
-        {
-          type: 'prose',
-          text: 'To verify it resolves, try importing the template component with its `.tsx` extension. An extensionless specifier will not resolve under `moduleResolution: bundler`, and the extensionful export above is what lets this type-check without consumers enabling `allowImportingTsExtensions`.',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');",
-        },
-      ],
-    },
-    {
-      title: 'Codemods',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file\u2019s `codemods` field at your codemods root, and author each one with `createCodemod` (transforms source files) or `createConfigCodemod` (rewrites the consumer\u2019s `astryx.config`).',
-        },
-        {
-          type: 'code',
-          lang: 'typescript',
-          code: "// codemods/v2-rename-prop.ts\nimport {createCodemod} from '@astryxdesign/cli/codemod';\n\nexport default createCodemod({\n  // version, description, transform, ...\n});",
-        },
-        {
-          type: 'prose',
-          text: 'The codemod helpers live in `@astryxdesign/cli/codemod`, not `@astryxdesign/core/authoring` like the doc, integration, and template helpers. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
-        },
-      ],
-    },
-    {
-      title: 'How It Works',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Every CLI command loads the consumer\u2019s `astryx.config`, resolves each listed integration\u2019s manifest from `node_modules`, and discovers its contributions. Everything is validated against one strict schema at the load boundary. The `create*` helpers do not validate. They are identity functions whose value is their TypeScript surface, so validation happens when the CLI loads the file, not when you author it.',
-        },
-        {
-          type: 'prose',
-          text: 'Discovery is resilient. A broken or misconfigured integration is skipped with a single non-blocking warning on stderr instead of crashing the CLI, and it never corrupts a `--json` stdout envelope. Everyday commands keep working with the remaining valid contributions.',
-        },
-        {
-          type: 'prose',
-          text: 'To inspect problems, run `astryx validate-integration <package>` for a detailed report on one package, or `astryx doctor` for an overall health check of the setup.',
-        },
-      ],
-    },
-  ],
-};