Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): build --type doc|theme points to search (#10401)

Joeyb3fb292b455a
diff --git a/.changeset/build-type-search-pointer.md b/.changeset/build-type-search-pointer.md
new file mode 100644
index 0000000000..659016b900
--- /dev/null
+++ b/.changeset/build-type-search-pointer.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx build --type doc` and `--type theme` now point to `astryx search <query> --type doc` or `--type theme`: a build kit has no docs or themes, so build says so once on stderr and names the search that finds them. Stdout, JSON output and exit codes are unchanged.
+
+@josephfarina
diff --git a/docs/specs/AST-048-build-recommendation/spec.md b/docs/specs/AST-048-build-recommendation/spec.md
index dc045dfd7a..b2a3c5e17f 100644
--- a/docs/specs/AST-048-build-recommendation/spec.md
+++ b/docs/specs/AST-048-build-recommendation/spec.md
@@ -201,6 +201,13 @@ own ranking and output, and template owners own what each template is.
`missingPackages`, and `installCommand` carry (which packages, which ranges,
and whether there is a command), as ranking decides values under FR11;
`spec:AST-017` classifies a change in those values.
+- **FR23 — Docs and themes point to search.** A build kit has
+ no doc or theme group. With `--type doc` or `--type theme`, build MUST return
+ what it returns without the note: the empty kit for a query, the playbook
+ without one, with the same stdout, JSON response and exit status. In text
+ mode, with or without a query, build MUST also print one stderr note naming
+ `astryx search <query> --type doc` or `--type theme`; JSON mode prints no
+ note.
### Platform support
@@ -258,6 +265,7 @@ This record changes these surfaces:
| FR20 | Readiness fixture tests | a source that imports StyleX at run time and one that imports only its types, with and without a declared compiler | A missing compiler with no note, a note beside a declared compiler or for a type-only import, or a compiler in the install command |
| FR21 | Build kit and template copy tests | the start and each alternative against the receipt for the same template and directory; default and `--verbose` text | A recommended template without the fields, a value the receipt would not carry, an empty `notes` on a build entry, or a field the text never shows |
| FR22 | CLI exit-code and response type tests | a scaffold and a build with packages and a compiler missing | A changed exit status, or an existing field whose name or type changes |
+| FR23 | CLI text and JSON tests | `--type doc` and `--type theme`, with and without a query, in text and JSON mode; `--type component` | A note on stdout, a second note, a note in JSON mode or for a kind the kit has, or stdout, JSON or exit status that differs from the same build without the note |
## Decision log
diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjs
index 912b2f100b..09bc179706 100644
--- a/packages/cli/clients/cli/commands/build.mjs
+++ b/packages/cli/clients/cli/commands/build.mjs
@@ -66,6 +66,24 @@ function printPlaybook(playbook) {
);
}
+/** The domains search finds that a build kit has no group for. */
+const SEARCH_ONLY_TYPES = ['doc', 'theme'];
+
+/**
+ * In text mode, say once on stderr that a kit has no docs or themes and name
+ * the search that finds them, as other command notes do (`search`,
+ * `integration pack --check`). Stdout, the JSON envelope and the exit status
+ * stay as they are.
+ * @param {string | undefined} type
+ * @param {boolean} json
+ */
+function pointToSearch(type, json) {
+ if (json || !type || !SEARCH_ONLY_TYPES.includes(type)) return;
+ console.error(
+ `Note: a build kit has no ${type}s. Find them with \`${formatCliCommand(`search <query> --type ${type}`)}\`.`,
+ );
+}
+
/**
* @param {import('commander').Command} program
*/
@@ -89,6 +107,7 @@ export function registerBuild(program) {
// one. Counting it as a result keeps "what did this run answer with"
// true for the no-argument form too.
const playbook = resultSet({count: 1, resultKind: 'doc'});
+ pointToSearch(options.type, json);
if (json) {
jsonOut(result);
return playbook;
@@ -101,8 +120,7 @@ export function registerBuild(program) {
// Parse --limit to a number; the API validates it (positive integer) and
// throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than
// pre-rejecting with a generic code here (parity with `search`).
- const limit =
- options.limit != null ? Number(options.limit) : 60;
+ const limit = options.limit != null ? Number(options.limit) : 60;
/** @type {import('../../../api/build/build.type.mjs').BuildKitResponse} */
let result;
@@ -151,6 +169,7 @@ export function registerBuild(program) {
jsonOut(result);
return answered;
}
+ pointToSearch(options.type, json);
if (!hasResults && !start) {
emit(
@@ -227,7 +246,13 @@ export function registerBuild(program) {
start,
verbose
? {
- fields: ['name', 'package', 'displayName', 'description', 'command'],
+ fields: [
+ 'name',
+ 'package',
+ 'displayName',
+ 'description',
+ 'command',
+ ],
format: {command: formatCliCommand},
}
: brief(['name', 'package', 'description', 'command']),
@@ -242,7 +267,9 @@ export function registerBuild(program) {
),
records(
start.alternatives,
- verbose ? full : brief(['name', 'package', 'description', 'command']),
+ verbose
+ ? full
+ : brief(['name', 'package', 'description', 'command']),
),
);
}
@@ -283,7 +310,9 @@ export function registerBuild(program) {
? [
records(
shown(domain),
- verbose ? full : brief(['name', 'package', 'deprecated', 'description']),
+ verbose
+ ? full
+ : brief(['name', 'package', 'deprecated', 'description']),
),
]
: []),
diff --git a/packages/cli/clients/cli/commands/type-choices.test.mjs b/packages/cli/clients/cli/commands/type-choices.test.mjs
index 1292ee2172..640cff8129 100644
--- a/packages/cli/clients/cli/commands/type-choices.test.mjs
+++ b/packages/cli/clients/cli/commands/type-choices.test.mjs
@@ -6,6 +6,8 @@
* name that same set, so the four cannot drift apart.
*/
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
import {describe, expect, it} from 'vitest';
import {SEARCH_DOMAINS} from '../../../api/search/_query.mjs';
import {doc as buildCommand} from './build.doc.mjs';
@@ -93,3 +95,40 @@ describe.each([
check(type, response.data);
});
});
+
+describe('build --type doc|theme points to search', () => {
+ const BIN = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
+ /** @param {string[]} args */
+ const cli = args =>
+ spawnSync(process.execPath, [BIN, 'build', ...args], {encoding: 'utf8'});
+
+ it.each([
+ ['doc', ['neutral']],
+ ['theme', ['neutral']],
+ ['doc', []],
+ ['theme', []],
+ ])(
+ 'names search once on stderr for %s (query: %j)',
+ (type, query) => {
+ const run = cli([...query, '--type', type]);
+ expect(run.status).toBe(0);
+ expect(run.stderr.match(/Note: a build kit has no/g) ?? []).toHaveLength(
+ 1,
+ );
+ expect(run.stderr).toContain(`search <query> --type ${type}`);
+ expect(run.stdout).not.toContain('Note: a build kit');
+ },
+ 60_000,
+ );
+
+ it('says nothing in JSON mode or for a kind a kit has', () => {
+ expect(cli(['neutral', '--type', 'doc', '--json']).stderr).toBe('');
+ expect(cli(['neutral', '--type', 'component']).stderr).toBe('');
+ }, 60_000);
+
+ it('reads an empty --type as no filter', async () => {
+ const none = await build('settings page');
+ const empty = await build('settings page', {type: /** @type {any} */ ('')});
+ expect(empty).toEqual(none);
+ });
+});