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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/cli/api/discover/_adapter.mjs b/packages/cli/api/discover/_adapter.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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,