Skip to content

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

TypeScript

fix(cli): a broken integration manifest fails loudly instead of vanishing (#5119)

Cindy Zhang915a7aafbf12
diff --git a/.changeset/loud-broken-integration-manifest.md b/.changeset/loud-broken-integration-manifest.md
new file mode 100644
index 0000000000..ef8020bce0
--- /dev/null
+++ b/.changeset/loud-broken-integration-manifest.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] An integration whose manifest fails to load is no longer silent. A manifest that throws on import — the common case being one still calling a `create*` authoring factory, removed in 0.3.0 — contributes nothing, and the CLI treated that as if the package had never been configured: `astryx discover` answered `No integrations configured.` while `astryx.config.mjs` plainly configured one, and no command said a word. The only way to find out was to already suspect it and run `validate-integration` by name. Meta's internal `@nest/xds-meta` sat invisible to CLI discovery for a week that way, and the app team's conclusion was that the components did not exist.
+
+The load error now counts as an integration issue, so the existing one-line stderr nudge fires on `component`, `template` and `upgrade`, and `discover` — the command whose whole job is listing integrations — nudges too, as does `search`. `discover` also stops reporting `configured: false` for a project that configured an integration that failed to load; the empty state now distinguishes "you configured nothing" from "what you configured contributed nothing", which is the distinction `meta.configured` was introduced to carry.
+
+Nothing becomes fatal: the warning is best-effort, stderr-only, suppressed under `--json`, and never changes an exit code. Broken contributions are still skipped exactly as before.
+
+@cixzhang
diff --git a/packages/cli/api/discover/_adapter.mjs b/packages/cli/api/discover/_adapter.mjs
index ec5eea814d..b8be0a0933 100644
--- a/packages/cli/api/discover/_adapter.mjs
+++ b/packages/cli/api/discover/_adapter.mjs
@@ -62,9 +62,11 @@ function validateDocs(docs) {
*
* External packages come from configured integrations that declare a components
* root; each becomes a scannable package keyed by its docsDir. `configured`
- * reports whether ANY integration declared a components root — it lets an empty
- * result distinguish "nothing configured" (`false`) from "configured but
- * nothing discovered" (`true`), which the list leaf surfaces as `meta`.
+ * reports whether the project configured ANY integration — including one whose
+ * manifest failed to load, which contributes nothing but is emphatically not
+ * "nothing configured". It lets an empty result distinguish "nothing
+ * configured" (`false`) from "configured but nothing discovered" (`true`),
+ * which the list leaf surfaces as `meta`.
*
* @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
*/
@@ -84,7 +86,7 @@ export async function discoverPackages() {
docsDir: integration.components,
}));
if (explicitPackages.length === 0) {
- return {packages: [], configured: false};
+ return {packages: [], configured: loadedIntegrations.length > 0};
}
const packages = scanAllPackages(
diff --git a/packages/cli/clients/cli/commands/discover.broken-integration.test.mjs b/packages/cli/clients/cli/commands/discover.broken-integration.test.mjs
new file mode 100644
index 0000000000..21f5ece510
--- /dev/null
+++ b/packages/cli/clients/cli/commands/discover.broken-integration.test.mjs
@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` and `astryx search` against an integration whose
+ * manifest fails to load.
+ *
+ * A manifest authored against a removed API throws on import, contributes
+ * nothing, and used to leave discover reporting "No integrations configured."
+ * — the package simply vanished. These drive the real CLI in-process against a
+ * hermetic project (astryx.config.mjs + a throwing astryx.integration.mjs under
+ * node_modules) and pin the loud behavior.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const CORE_DIR = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../../../core',
+);
+
+let tmpDir;
+let project;
+
+/**
+ * Configure `@test/broken` with a manifest that throws at import. Calling an
+ * undeclared factory stands in for the real failure this came from: a 0.2.x
+ * manifest still calling `createIntegration`, which 0.3.0 removed.
+ */
+function buildBrokenIntegration() {
+ const intDir = path.join(project, 'node_modules', '@test', 'broken');
+ fs.mkdirSync(path.join(intDir, 'components'), {recursive: true});
+ fs.writeFileSync(
+ path.join(intDir, 'package.json'),
+ JSON.stringify({name: '@test/broken', version: '1.2.3'}),
+ );
+ fs.writeFileSync(
+ path.join(intDir, 'astryx.integration.mjs'),
+ `export default createIntegration({components: './components'});\n`,
+ );
+ fs.writeFileSync(
+ path.join(project, 'astryx.config.mjs'),
+ `export default {integrations: ['@test/broken']};\n`,
+ );
+}
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-broken-'));
+ project = path.join(tmpDir, 'project');
+ fs.mkdirSync(project, {recursive: true});
+ fs.writeFileSync(
+ path.join(project, 'package.json'),
+ JSON.stringify({name: 'proj', version: '1.0.0'}),
+ );
+ buildBrokenIntegration();
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('astryx discover with a manifest that fails to load', () => {
+ it('warns on stderr and does not claim nothing is configured', async () => {
+ const {status, stdout, stderr} = await runCli(['discover'], {cwd: project});
+
+ expect(status).toBe(0);
+ expect(stderr).toContain(
+ 'Warning: @test/broken has 1 integration issue(s). ' +
+ 'Run: astryx validate-integration @test/broken',
+ );
+ expect(stdout).not.toContain('No integrations configured.');
+ expect(stdout).toContain('No external components found in configured integrations.');
+ });
+
+ it('reports meta.configured=true in --json, with the nudge suppressed', async () => {
+ const {status, stdout, stderr} = await runCli(['discover', '--json'], {
+ cwd: project,
+ });
+
+ expect(status).toBe(0);
+ expect(JSON.parse(stdout).meta).toEqual({configured: true});
+ expect(stderr).not.toContain('integration issue');
+ });
+});
+
+describe('astryx search with a manifest that fails to load', () => {
+ // search needs a resolvable @astryxdesign/core; without one it errors out
+ // before it can list anything, which is not the case under test.
+ beforeEach(() => {
+ const scope = path.join(project, 'node_modules', '@astryxdesign');
+ fs.mkdirSync(scope, {recursive: true});
+ fs.symlinkSync(CORE_DIR, path.join(scope, 'core'), 'dir');
+ });
+
+ it('warns on stderr, and suppresses the nudge under --json', async () => {
+ const {status, stderr} = await runCli(['search', 'button'], {cwd: project});
+
+ expect(status).toBe(0);
+ expect(stderr).toContain(
+ 'Warning: @test/broken has 1 integration issue(s). ' +
+ 'Run: astryx validate-integration @test/broken',
+ );
+
+ const asJson = await runCli(['search', 'button', '--json'], {cwd: project});
+ expect(asJson.status).toBe(0);
+ expect(asJson.stderr).not.toContain('integration issue');
+ }, 30_000);
+});
diff --git a/packages/cli/clients/cli/commands/discover.mjs b/packages/cli/clients/cli/commands/discover.mjs
index 46460f3313..0df78ccf4f 100644
--- a/packages/cli/clients/cli/commands/discover.mjs
+++ b/packages/cli/clients/cli/commands/discover.mjs
@@ -15,6 +15,8 @@ import {jsonOut} from '../../../foundation/response/json.mjs';
import {emit, section, text, record, records, list, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {discover as discoverApi} from '../../../api/discover/discover.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {doc as discoverCommand} from './discover.doc.mjs';
@@ -41,6 +43,16 @@ export function registerDiscover(program) {
const zh = program.opts().zh || false;
const run = getCliInvocation();
+ // Non-blocking nudge: if any configured integration has validation
+ // issues, print one compact line to stderr pointing at
+ // validate-integration. Best-effort; suppressed in --json mode.
+ try {
+ const project = await Project.load(process.cwd());
+ await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+ } catch {
+ // Never let the nudge break the command.
+ }
+
let result;
try {
result = await discoverApi(query, {components: options.components, lang, zh});
diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjs
index e45a9927f3..a601c60704 100644
--- a/packages/cli/clients/cli/commands/search.mjs
+++ b/packages/cli/clients/cli/commands/search.mjs
@@ -26,6 +26,8 @@ import {emit, section, text, records} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {search as searchApi} from '../../../api/search/search.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
import {doc as searchCommand} from './search.doc.mjs';
import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -41,6 +43,13 @@ export function registerSearch(program) {
) => {
const json = program.opts().json || false;
+ try {
+ const project = await Project.load(process.cwd());
+ await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+ } catch {
+ // Never let the nudge break the command.
+ }
+
// 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.
diff --git a/packages/cli/foundation/integrations/integration-warnings.test.mjs b/packages/cli/foundation/integrations/integration-warnings.test.mjs
index 39d378f5af..f27f1a51b4 100644
--- a/packages/cli/foundation/integrations/integration-warnings.test.mjs
+++ b/packages/cli/foundation/integrations/integration-warnings.test.mjs
@@ -68,6 +68,23 @@ describe('warnOnIntegrationIssues', () => {
expect(errLines).toHaveLength(0);
});
+ it('warns for a manifest that failed to load, which declares no roots', async () => {
+ // loadIntegrations records __loadError and no contribution roots, so every
+ // on-disk check finds nothing — without the load error itself counting as
+ // an issue, a stale manifest is silent everywhere.
+ const integration = {
+ ...loaded({name: '@acme/stale'}),
+ __loadError: 'createIntegration is not a function',
+ };
+ await warnOnIntegrationIssues([integration], {json: false});
+
+ expect(errLines).toHaveLength(1);
+ expect(errLines[0]).toBe(
+ 'Warning: @acme/stale has 1 integration issue(s). ' +
+ 'Run: astryx validate-integration @acme/stale',
+ );
+ });
+
it('emits nothing for an integration with no issues', async () => {
// Existing components root with no broken contributions → no issues.
const componentsRoot = path.join(tmpDir, 'components');
diff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjs
index 7522e8a4b1..20762efdac 100644
--- a/packages/cli/foundation/integrations/validate-contributions.mjs
+++ b/packages/cli/foundation/integrations/validate-contributions.mjs
@@ -149,6 +149,13 @@ export async function validateLoadedIntegration(loaded) {
/** @type {Issue[]} */
const issues = [];
if (!loaded || typeof loaded !== 'object') return issues;
+ // A manifest that threw on import (or failed the schema) carries a load-error
+ // marker and no contribution roots, so every check below would find nothing
+ // and report a clean integration — which is how a stale manifest used to go
+ // silently invisible. The load error IS the issue.
+ if (loaded.__loadError) {
+ return [issueError('integration_error', loaded.__loadError)];
+ }
checkRoots(
{
components: loaded.components,