@astryxdesign/cli 0.1.0-canary.d150e45 → 0.1.0-canary.d3c9e29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -75
- package/docs/working-with-ai.doc.mjs +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ npx astryx docs migration
|
|
|
11
11
|
npx astryx template --list
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Finding things: `astryx search`
|
|
15
15
|
|
|
16
16
|
When you don't know whether what you need is a component, a hook, a docs topic,
|
|
17
17
|
or a template, search across all of them at once. Results are ranked by
|
|
@@ -50,20 +50,20 @@ Options:
|
|
|
50
50
|
|
|
51
51
|
## Commands
|
|
52
52
|
|
|
53
|
-
| Command | Description
|
|
54
|
-
| ------------- |
|
|
53
|
+
| Command | Description |
|
|
54
|
+
| ------------- | ---------------------------------------------------------------------------------------------------- |
|
|
55
55
|
| `init` | Initialize the design system in your project: installs packages, sets up theming, adds AI agent docs |
|
|
56
|
-
| `component` | List components or print detailed docs, props, usage examples, and source
|
|
57
|
-
| `search` | Find components, hooks, docs, and templates in one ranked, cross-domain result set
|
|
58
|
-
| `docs` | Print reference documentation (tokens, theme, color, typography, spacing, etc.)
|
|
59
|
-
| `template` | Inject page or block templates into your project
|
|
60
|
-
| `hook` | List hooks and print hook documentation
|
|
61
|
-
| `swizzle` | Copy component source into your project for deep customization
|
|
62
|
-
| `upgrade` | Run codemods to migrate between versions
|
|
63
|
-
| `theme build` | Compile a defineTheme file to production CSS and JS
|
|
64
|
-
| `discover` | Discover external packages and components
|
|
65
|
-
| `gap-report` | Report a gap when a component doesn't meet your needs
|
|
66
|
-
| `doctor` | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)
|
|
56
|
+
| `component` | List components or print detailed docs, props, usage examples, and source |
|
|
57
|
+
| `search` | Find components, hooks, docs, and templates in one ranked, cross-domain result set |
|
|
58
|
+
| `docs` | Print reference documentation (tokens, theme, color, typography, spacing, etc.) |
|
|
59
|
+
| `template` | Inject page or block templates into your project |
|
|
60
|
+
| `hook` | List hooks and print hook documentation |
|
|
61
|
+
| `swizzle` | Copy component source into your project for deep customization |
|
|
62
|
+
| `upgrade` | Run codemods to migrate between versions |
|
|
63
|
+
| `theme build` | Compile a defineTheme file to production CSS and JS |
|
|
64
|
+
| `discover` | Discover external packages and components |
|
|
65
|
+
| `gap-report` | Report a gap when a component doesn't meet your needs |
|
|
66
|
+
| `doctor` | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code) |
|
|
67
67
|
|
|
68
68
|
### Global options
|
|
69
69
|
|
|
@@ -122,46 +122,46 @@ if (isError(result)) {
|
|
|
122
122
|
|
|
123
123
|
### Error codes
|
|
124
124
|
|
|
125
|
-
| Code
|
|
126
|
-
|
|
|
127
|
-
| `ERR_UNKNOWN`
|
|
128
|
-
| `ERR_UNKNOWN_COMMAND`
|
|
129
|
-
| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`).
|
|
130
|
-
| `ERR_INVALID_OPTION`
|
|
131
|
-
| `ERR_INVALID_ARGUMENT`
|
|
132
|
-
| `ERR_MISSING_ARGUMENT`
|
|
133
|
-
| `ERR_INVALID_LANG`
|
|
134
|
-
| `ERR_INVALID_DETAIL`
|
|
135
|
-
| `ERR_NODE_VERSION`
|
|
136
|
-
| `ERR_CORE_NOT_FOUND`
|
|
137
|
-
| `ERR_UNKNOWN_COMPONENT`
|
|
138
|
-
| `ERR_UNKNOWN_HOOK`
|
|
139
|
-
| `ERR_UNKNOWN_TOPIC`
|
|
140
|
-
| `ERR_UNKNOWN_SECTION`
|
|
141
|
-
| `ERR_UNKNOWN_CATEGORY`
|
|
142
|
-
| `ERR_UNKNOWN_TEMPLATE`
|
|
143
|
-
| `ERR_UNKNOWN_PACKAGE`
|
|
144
|
-
| `ERR_UNKNOWN_AGENT`
|
|
145
|
-
| `ERR_UNKNOWN_FEATURE`
|
|
146
|
-
| `ERR_UNKNOWN_CODEMOD`
|
|
147
|
-
| `ERR_NOT_FOUND`
|
|
148
|
-
| `ERR_NO_DOC`
|
|
149
|
-
| `ERR_NO_SHOWCASE`
|
|
150
|
-
| `ERR_NO_SOURCE`
|
|
151
|
-
| `ERR_INVALID_DOC`
|
|
152
|
-
| `ERR_FILE_NOT_FOUND`
|
|
153
|
-
| `ERR_FILE_EXISTS`
|
|
154
|
-
| `ERR_PATH_TRAVERSAL`
|
|
155
|
-
| `ERR_WRITE_FAILED`
|
|
156
|
-
| `ERR_THEME_INVALID`
|
|
157
|
-
| `ERR_THEME_LOAD`
|
|
158
|
-
| `ERR_TEMPLATE_CONFIG`
|
|
159
|
-
| `ERR_TEMPLATE_GET`
|
|
160
|
-
| `ERR_VERSION_DETECT`
|
|
161
|
-
| `ERR_INVALID_VERSION`
|
|
162
|
-
| `ERR_DEP_MISSING`
|
|
163
|
-
| `ERR_GH_CLI`
|
|
164
|
-
| `ERR_GAP_REPORT_FAILED`
|
|
125
|
+
| Code | Meaning |
|
|
126
|
+
| ------------------------ | -------------------------------------------------------------------------------------- |
|
|
127
|
+
| `ERR_UNKNOWN` | Generic fallback for any error without a more specific code. |
|
|
128
|
+
| `ERR_UNKNOWN_COMMAND` | A top-level command name was not recognized (e.g. `astryx bogus`). |
|
|
129
|
+
| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`). |
|
|
130
|
+
| `ERR_INVALID_OPTION` | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
|
|
131
|
+
| `ERR_INVALID_ARGUMENT` | An option/argument value was rejected, or required flags were missing. |
|
|
132
|
+
| `ERR_MISSING_ARGUMENT` | A required positional argument was omitted (e.g. `astryx theme build` with no file). |
|
|
133
|
+
| `ERR_INVALID_LANG` | `--lang` was given a value outside its choices (`en`, `zh`, `dense`). |
|
|
134
|
+
| `ERR_INVALID_DETAIL` | `--detail` was given a value outside its choices (`full`, `compact`, `brief`). |
|
|
135
|
+
| `ERR_NODE_VERSION` | The running Node.js version is below the supported minimum. |
|
|
136
|
+
| `ERR_CORE_NOT_FOUND` | `@astryxdesign/core` could not be located (not installed / not in a monorepo). |
|
|
137
|
+
| `ERR_UNKNOWN_COMPONENT` | No component matched the requested name. |
|
|
138
|
+
| `ERR_UNKNOWN_HOOK` | No hook matched the requested name. |
|
|
139
|
+
| `ERR_UNKNOWN_TOPIC` | No docs topic matched the requested name. |
|
|
140
|
+
| `ERR_UNKNOWN_SECTION` | A docs topic exists but the requested section within it does not. |
|
|
141
|
+
| `ERR_UNKNOWN_CATEGORY` | A `--category` filter value did not match any known category. |
|
|
142
|
+
| `ERR_UNKNOWN_TEMPLATE` | No template matched the requested name. |
|
|
143
|
+
| `ERR_UNKNOWN_PACKAGE` | No package matched the requested name (discover). |
|
|
144
|
+
| `ERR_UNKNOWN_AGENT` | An unrecognized `--agent` value was passed (agent docs / init). |
|
|
145
|
+
| `ERR_UNKNOWN_FEATURE` | An unrecognized `--features` value was passed to `init`. |
|
|
146
|
+
| `ERR_UNKNOWN_CODEMOD` | A `--codemod` value did not match any registered codemod (upgrade). |
|
|
147
|
+
| `ERR_NOT_FOUND` | A discover/lookup query matched nothing in any package. |
|
|
148
|
+
| `ERR_NO_DOC` | A component exists but has no typed `.doc.mjs` file. |
|
|
149
|
+
| `ERR_NO_SHOWCASE` | No showcase exists for the requested component. |
|
|
150
|
+
| `ERR_NO_SOURCE` | No source file could be located for the component/template. |
|
|
151
|
+
| `ERR_INVALID_DOC` | A component's docs failed validation (malformed `.doc.mjs`). |
|
|
152
|
+
| `ERR_FILE_NOT_FOUND` | A required input file did not exist. |
|
|
153
|
+
| `ERR_FILE_EXISTS` | Refused to overwrite an existing file in non-interactive mode. |
|
|
154
|
+
| `ERR_PATH_TRAVERSAL` | A path escaped its allowed root, or a name contained traversal markers. |
|
|
155
|
+
| `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). |
|
|
156
|
+
| `ERR_THEME_INVALID` | A theme definition was missing a required property (e.g. `name`). |
|
|
157
|
+
| `ERR_THEME_LOAD` | A theme file could not be loaded / parsed into a `defineTheme` result. |
|
|
158
|
+
| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id). |
|
|
159
|
+
| `ERR_TEMPLATE_GET` | A configured `template.get` threw or returned an invalid value. |
|
|
160
|
+
| `ERR_VERSION_DETECT` | The current `@astryxdesign/core` version could not be detected. |
|
|
161
|
+
| `ERR_INVALID_VERSION` | A `--from`/`--to` value was not a valid semver string. |
|
|
162
|
+
| `ERR_DEP_MISSING` | A required external dependency (e.g. jscodeshift) is missing. |
|
|
163
|
+
| `ERR_GH_CLI` | GitHub CLI (`gh`) is not installed or not authenticated. |
|
|
164
|
+
| `ERR_GAP_REPORT_FAILED` | Filing a gap report failed (disabled, or the integration errored). |
|
|
165
165
|
|
|
166
166
|
## Capability manifest (agent discovery)
|
|
167
167
|
|
|
@@ -186,25 +186,59 @@ Shape:
|
|
|
186
186
|
"version": "0.0.14",
|
|
187
187
|
"description": "Design system CLI — components, themes, and tooling",
|
|
188
188
|
"globalOptions": [
|
|
189
|
-
{
|
|
190
|
-
|
|
191
|
-
|
|
189
|
+
{
|
|
190
|
+
"flag": "--json",
|
|
191
|
+
"type": "boolean",
|
|
192
|
+
"description": "Output as typed JSON…",
|
|
193
|
+
},
|
|
194
|
+
{
|
|
195
|
+
"flag": "--lang <locale>",
|
|
196
|
+
"type": "enum",
|
|
197
|
+
"choices": ["en", "zh", "dense"],
|
|
198
|
+
},
|
|
199
|
+
{
|
|
200
|
+
"flag": "--detail <level>",
|
|
201
|
+
"type": "enum",
|
|
202
|
+
"choices": ["full", "compact", "brief"],
|
|
203
|
+
"default": "full",
|
|
204
|
+
},
|
|
192
205
|
],
|
|
193
206
|
"commands": [
|
|
194
207
|
{
|
|
195
208
|
"name": "component",
|
|
196
209
|
"description": "List components or print component docs",
|
|
197
|
-
"arguments": [
|
|
198
|
-
|
|
210
|
+
"arguments": [
|
|
211
|
+
{
|
|
212
|
+
"name": "name",
|
|
213
|
+
"required": false,
|
|
214
|
+
"variadic": false,
|
|
215
|
+
"description": "",
|
|
216
|
+
},
|
|
217
|
+
],
|
|
218
|
+
"options": [
|
|
219
|
+
{
|
|
220
|
+
"flag": "--props",
|
|
221
|
+
"type": "boolean",
|
|
222
|
+
"description": "Print only the props table",
|
|
223
|
+
},
|
|
224
|
+
],
|
|
199
225
|
"json": true,
|
|
200
|
-
"responseTypes": [
|
|
201
|
-
|
|
202
|
-
|
|
226
|
+
"responseTypes": [
|
|
227
|
+
"component.list",
|
|
228
|
+
"component.detail",
|
|
229
|
+
"component.detail.props",
|
|
230
|
+
"…",
|
|
231
|
+
],
|
|
232
|
+
"examples": ["astryx component Button --props --json"],
|
|
233
|
+
},
|
|
203
234
|
// …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
|
|
204
235
|
],
|
|
205
236
|
"jsonSupported": ["component", "docs", "…"],
|
|
206
|
-
"responseTypes": {
|
|
207
|
-
|
|
237
|
+
"responseTypes": {
|
|
238
|
+
"component": ["component.list", "…"],
|
|
239
|
+
"theme build": ["theme.build"],
|
|
240
|
+
},
|
|
241
|
+
},
|
|
208
242
|
}
|
|
209
243
|
```
|
|
210
244
|
|
|
@@ -225,7 +259,15 @@ For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest
|
|
|
225
259
|
The same logic that powers `xds --json` is available as importable, type-safe functions:
|
|
226
260
|
|
|
227
261
|
```typescript
|
|
228
|
-
import {
|
|
262
|
+
import {
|
|
263
|
+
component,
|
|
264
|
+
docs,
|
|
265
|
+
discover,
|
|
266
|
+
template,
|
|
267
|
+
hook,
|
|
268
|
+
search,
|
|
269
|
+
AstryxError,
|
|
270
|
+
} from '@astryxdesign/cli/api';
|
|
229
271
|
|
|
230
272
|
// Same result as: xds --json component Button
|
|
231
273
|
const btn = await component('Button');
|
|
@@ -359,16 +401,16 @@ No failures — but review the ⚠ warnings above when you can.
|
|
|
359
401
|
|
|
360
402
|
### Checks
|
|
361
403
|
|
|
362
|
-
| Check
|
|
363
|
-
|
|
|
364
|
-
| Node.js version
|
|
365
|
-
| @astryxdesign/core installed
|
|
366
|
-
| Version alignment
|
|
367
|
-
| Theme packages
|
|
368
|
-
| astryx.config.mjs
|
|
369
|
-
| AI agent docs
|
|
370
|
-
| Peer dependencies
|
|
371
|
-
| Package manager
|
|
404
|
+
| Check | Status it can return | What it verifies |
|
|
405
|
+
| ---------------------------- | -------------------- | -------------------------------------------------------------------- |
|
|
406
|
+
| Node.js version | pass / fail | Running Node meets the CLI's minimum |
|
|
407
|
+
| @astryxdesign/core installed | pass / fail | `@astryxdesign/core` is resolvable from the project |
|
|
408
|
+
| Version alignment | pass / warn / info | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli` |
|
|
409
|
+
| Theme packages | pass / warn | An `@astryxdesign/theme-*` package is installed and a theme is wired |
|
|
410
|
+
| astryx.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |
|
|
411
|
+
| AI agent docs | pass / warn / info | Agent docs exist and contain the XDS section markers |
|
|
412
|
+
| Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed |
|
|
413
|
+
| Package manager | info | Reports the detected package manager |
|
|
372
414
|
|
|
373
415
|
### CI gate
|
|
374
416
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astryxdesign/cli",
|
|
3
|
-
"version": "0.1.0-canary.
|
|
3
|
+
"version": "0.1.0-canary.d3c9e29",
|
|
4
4
|
"displayName": "CLI",
|
|
5
5
|
"description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
|
|
6
6
|
"author": "Meta Open Source",
|
|
@@ -54,9 +54,9 @@
|
|
|
54
54
|
"jscodeshift": "^17.3.0"
|
|
55
55
|
},
|
|
56
56
|
"peerDependencies": {
|
|
57
|
-
"@astryxdesign/core": "0.1.0-canary.
|
|
58
|
-
"@astryxdesign/lab": "0.1.0-canary.
|
|
59
|
-
"@astryxdesign/theme-neutral": "0.1.0-canary.
|
|
57
|
+
"@astryxdesign/core": "0.1.0-canary.d3c9e29",
|
|
58
|
+
"@astryxdesign/lab": "0.1.0-canary.d3c9e29",
|
|
59
|
+
"@astryxdesign/theme-neutral": "0.1.0-canary.d3c9e29"
|
|
60
60
|
},
|
|
61
61
|
"peerDependenciesMeta": {
|
|
62
62
|
"@astryxdesign/core": {
|
|
@@ -70,9 +70,9 @@
|
|
|
70
70
|
}
|
|
71
71
|
},
|
|
72
72
|
"devDependencies": {
|
|
73
|
-
"@astryxdesign/core": "0.1.0-canary.
|
|
74
|
-
"@astryxdesign/lab": "0.1.0-canary.
|
|
75
|
-
"@astryxdesign/theme-neutral": "0.1.0-canary.
|
|
73
|
+
"@astryxdesign/core": "0.1.0-canary.d3c9e29",
|
|
74
|
+
"@astryxdesign/lab": "0.1.0-canary.d3c9e29",
|
|
75
|
+
"@astryxdesign/theme-neutral": "0.1.0-canary.d3c9e29"
|
|
76
76
|
},
|
|
77
77
|
"scripts": {
|
|
78
78
|
"astryx": "node bin/astryx.mjs",
|