@astryxdesign/cli 0.4.3-canary.71781fc → 0.4.3-canary.84ceb39

package/api/discover/_adapter.d.mts

@@ -6,9 +6,11 @@
  *
  * 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}>}
  */

package/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(

package/assets/templates/blocks/components/BottomSheet/BottomSheetHeights.doc.mjs

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — Height variants',
+  displayName: 'Bottom Sheet — Height variants',
+  description:
+    'Compares hug, capped, and tall starting heights for different amounts of content.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Stack',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetHeights.tsx

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  BottomSheet,
+  type BottomSheetHeight,
+} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+const descriptions: Record<BottomSheetHeight, string> = {
+  hug: 'Hug fits short, bounded content.',
+  capped: 'Capped starts at a comfortable mid-height for lists and filters.',
+  tall: 'Tall reserves most of the viewport for long or changing content.',
+};
+
+export default function BottomSheetHeights() {
+  const [height, setHeight] = useState<BottomSheetHeight | null>(null);
+
+  return (
+    <>
+      <HStack gap={2} wrap="wrap">
+        <Button label="Open hug" onClick={() => setHeight('hug')} />
+        <Button label="Open capped" onClick={() => setHeight('capped')} />
+        <Button label="Open tall" onClick={() => setHeight('tall')} />
+      </HStack>
+      <BottomSheet
+        isOpen={height != null}
+        onOpenChange={isOpen => !isOpen && setHeight(null)}
+        label={`${height ?? 'Hug'} height`}
+        height={height ?? 'hug'}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>{height ?? 'Hug'} height</Heading>
+          <Divider />
+          <Text type="body">{descriptions[height ?? 'hug']}</Text>
+          <Button label="Close" onClick={() => setHeight(null)} />
+        </VStack>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetMobileKeyboard.doc.mjs

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — Mobile keyboard',
+  displayName: 'Bottom Sheet — Mobile keyboard',
+  description:
+    'Uses a tall, scrollable form that keeps focused controls visible above the mobile keyboard.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Stack',
+    'Text',
+    'TextArea',
+    'TextInput',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetMobileKeyboard.tsx

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {TextInput} from '@astryxdesign/core/TextInput';
+
+interface ProfileFormValues {
+  name: string;
+  email: string;
+  company: string;
+  role: string;
+  bio: string;
+  notes: string;
+}
+
+const initialValues: ProfileFormValues = {
+  name: '',
+  email: '',
+  company: '',
+  role: '',
+  bio: '',
+  notes: '',
+};
+
+export default function BottomSheetMobileKeyboard() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [values, setValues] = useState(initialValues);
+  const update =
+    (field: keyof ProfileFormValues) =>
+    (value: string): void =>
+      setValues(current => ({...current, [field]: value}));
+
+  return (
+    <>
+      <Button label="Edit profile" onClick={() => setIsOpen(true)} />
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Edit profile"
+        height="tall">
+        <form
+          onSubmit={event => {
+            event.preventDefault();
+            setIsOpen(false);
+          }}>
+          <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+            <Heading level={3}>Edit profile</Heading>
+            <Divider />
+            <Text type="supporting" color="secondary">
+              Focus fields throughout the form to see them remain visible above
+              the mobile keyboard.
+            </Text>
+            <TextInput
+              label="Name"
+              value={values.name}
+              onChange={update('name')}
+            />
+            <TextInput
+              label="Email"
+              type="email"
+              value={values.email}
+              onChange={update('email')}
+            />
+            <TextInput
+              label="Company"
+              value={values.company}
+              onChange={update('company')}
+            />
+            <TextInput
+              label="Role"
+              value={values.role}
+              onChange={update('role')}
+            />
+            <TextArea
+              label="Bio"
+              rows={5}
+              value={values.bio}
+              onChange={update('bio')}
+            />
+            <TextArea
+              label="Notes"
+              rows={5}
+              value={values.notes}
+              onChange={update('notes')}
+            />
+            <Button label="Save profile" type="submit" />
+          </VStack>
+        </form>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetNoScrim.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — No scrim',
+  displayName: 'Bottom Sheet — No scrim',
+  description:
+    'Keeps the page visible and interactive behind a non-modal bottom sheet.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Section',
+    'Stack',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetNoScrim.tsx

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function BottomSheetNoScrim() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [backgroundClicks, setBackgroundClicks] = useState(0);
+
+  return (
+    <Section padding={4}>
+      <VStack gap={3}>
+        <Heading level={3}>Nearby places</Heading>
+        <Text type="body">Background interactions: {backgroundClicks}</Text>
+        <Button
+          label="Interact with page"
+          variant="secondary"
+          onClick={() => setBackgroundClicks(count => count + 1)}
+        />
+        <Button label="Show place details" onClick={() => setIsOpen(true)} />
+      </VStack>
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Place details"
+        height="hug"
+        hasScrim={false}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>Central Park</Heading>
+          <Divider />
+          <Text type="body">
+            The page remains visible and interactive behind this sheet.
+          </Text>
+          <Button label="Close details" onClick={() => setIsOpen(false)} />
+        </VStack>
+      </BottomSheet>
+    </Section>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet',
+  displayName: 'Bottom Sheet',
+  description: 'A mobile filter surface that rises from the bottom edge.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'CheckboxInput',
+    'Divider',
+    'Heading',
+    'Section',
+    'Stack',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.tsx

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Stack';
+
+export default function BottomSheetShowcase() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [inStock, setInStock] = useState(false);
+  const [onSale, setOnSale] = useState(false);
+  const [freeShipping, setFreeShipping] = useState(false);
+
+  return (
+    <>
+      <Button label="Open sheet" onClick={() => setIsOpen(true)} />
+      <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label="Filters">
+        <Section padding={4}>
+          <VStack gap={4}>
+            <Heading level={3}>Filters</Heading>
+            <Divider />
+            <VStack gap={2}>
+              <CheckboxInput
+                label="In stock"
+                value={inStock}
+                onChange={setInStock}
+              />
+              <CheckboxInput
+                label="On sale"
+                value={onSale}
+                onChange={setOnSale}
+              />
+              <CheckboxInput
+                label="Free shipping"
+                value={freeShipping}
+                onChange={setFreeShipping}
+              />
+            </VStack>
+            <Button label="Apply" onClick={() => setIsOpen(false)} />
+          </VStack>
+        </Section>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.doc.mjs

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheetSwitcher',
+  name: 'Bottom Sheet Switcher',
+  displayName: 'Bottom Sheet Switcher',
+  description:
+    'A three-step flow that transitions between content-hugging sheets of different heights inside one shared dialog.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'BottomSheetSwitcher',
+    'Button',
+    'CheckboxInput',
+    'Divider',
+    'Heading',
+    'RadioList',
+    'Section',
+    'Stack',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.tsx

@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {BottomSheet, BottomSheetSwitcher} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';
+
+type NotificationSheetHeight = 'hug' | 'capped';
+
+interface NotificationOverviewSheetProps {
+  height: NotificationSheetHeight;
+  onCancel: () => void;
+  onContinue: () => void;
+}
+
+function NotificationOverviewSheet({
+  height,
+  onCancel,
+  onContinue,
+}: NotificationOverviewSheetProps) {
+  return (
+    <BottomSheet
+      sheetId="overview"
+      label="Set up notifications"
+      height={height}>
+      <Section padding={4}>
+        <VStack gap={4}>
+          <VStack gap={1}>
+            <Heading level={3}>Set up notifications</Heading>
+            <Text type="supporting" color="secondary">
+              Step 1 of 3
+            </Text>
+          </VStack>
+          <Divider />
+          <Text type="supporting" color="secondary">
+            Stay informed about activity that matters without checking back
+            throughout the day.
+          </Text>
+          <VStack gap={3}>
+            <VStack gap={1}>
+              <Text type="label">Important activity</Text>
+              <Text type="supporting" color="secondary">
+                Know when someone mentions you or needs your attention.
+              </Text>
+            </VStack>
+            <VStack gap={1}>
+              <Text type="label">Timely reminders</Text>
+              <Text type="supporting" color="secondary">
+                Get a reminder before work reaches its due date.
+              </Text>
+            </VStack>
+            <VStack gap={1}>
+              <Text type="label">Useful summaries</Text>
+              <Text type="supporting" color="secondary">
+                Catch up on anything you may have missed.
+              </Text>
+            </VStack>
+          </VStack>
+          <HStack gap={2} hAlign="end">
+            <Button label="Cancel" variant="secondary" onClick={onCancel} />
+            <Button label="Continue" onClick={onContinue} />
+          </HStack>
+        </VStack>
+      </Section>
+    </BottomSheet>
+  );
+}
+
+interface NotificationFrequencySheetProps {
+  height: NotificationSheetHeight;
+  onBack: () => void;
+  onContinue: () => void;
+}
+
+function NotificationFrequencySheet({
+  height,
+  onBack,
+  onContinue,
+}: NotificationFrequencySheetProps) {
+  const [frequency, setFrequency] = useState('daily');
+
+  return (
+    <BottomSheet
+      sheetId="frequency"
+      label="Notification frequency"
+      height={height}>
+      <Section padding={4}>
+        <VStack gap={4}>
+          <VStack gap={1}>
+            <Heading level={3}>How often?</Heading>
+            <Text type="supporting" color="secondary">
+              Step 2 of 3
+            </Text>
+          </VStack>
+          <Divider />
+          <RadioList
+            label="Notification frequency"
+            isLabelHidden
+            value={frequency}
+            onChange={setFrequency}>
+            <RadioListItem label="Immediately" value="immediately" />
+            <RadioListItem label="Daily" value="daily" />
+            <RadioListItem label="Weekly" value="weekly" />
+          </RadioList>
+          <HStack gap={2} hAlign="end">
+            <Button label="Back" variant="secondary" onClick={onBack} />
+            <Button label="Continue" onClick={onContinue} />
+          </HStack>
+        </VStack>
+      </Section>
+    </BottomSheet>
+  );
+}
+
+interface NotificationChannelsSheetProps {
+  height: NotificationSheetHeight;
+  onBack: () => void;
+  onFinish: () => void;
+}
+
+function NotificationChannelsSheet({
+  height,
+  onBack,
+  onFinish,
+}: NotificationChannelsSheetProps) {
+  const [email, setEmail] = useState(true);
+  const [pushNotifications, setPushNotifications] = useState(true);
+  const [textMessages, setTextMessages] = useState(false);
+
+  return (
+    <BottomSheet
+      sheetId="channels"
+      label="Notification channels"
+      height={height}>
+      <Section padding={4}>
+        <VStack gap={4}>
+          <VStack gap={1}>
+            <Heading level={3}>Where should we notify you?</Heading>
+            <Text type="supporting" color="secondary">
+              Step 3 of 3
+            </Text>
+          </VStack>
+          <Divider />
+          <Text type="supporting" color="secondary">
+            Choose any combination. You can change these preferences later.
+          </Text>
+          <VStack gap={2}>
+            <CheckboxInput label="Email" value={email} onChange={setEmail} />
+            <CheckboxInput
+              label="Push notifications"
+              value={pushNotifications}
+              onChange={setPushNotifications}
+            />
+            <CheckboxInput
+              label="Text messages"
+              value={textMessages}
+              onChange={setTextMessages}
+            />
+          </VStack>
+          <HStack gap={2} hAlign="end">
+            <Button label="Back" variant="secondary" onClick={onBack} />
+            <Button label="Finish" onClick={onFinish} />
+          </HStack>
+        </VStack>
+      </Section>
+    </BottomSheet>
+  );
+}
+
+interface MultiStepSwitcherExampleProps {
+  height: NotificationSheetHeight;
+  hasScrim?: boolean;
+}
+
+function MultiStepSwitcherExample({
+  height,
+  hasScrim = true,
+}: MultiStepSwitcherExampleProps) {
+  const [activeSheet, setActiveSheet] = useState<string | null>(null);
+
+  return (
+    <>
+      <Button
+        label="Set up notifications"
+        onClick={() => setActiveSheet('overview')}
+      />
+      <BottomSheetSwitcher
+        activeSheet={activeSheet}
+        onActiveSheetChange={setActiveSheet}
+        hasScrim={hasScrim}>
+        <NotificationOverviewSheet
+          height={height}
+          onCancel={() => setActiveSheet(null)}
+          onContinue={() => setActiveSheet('frequency')}
+        />
+        <NotificationFrequencySheet
+          height={height}
+          onBack={() => setActiveSheet('overview')}
+          onContinue={() => setActiveSheet('channels')}
+        />
+        <NotificationChannelsSheet
+          height={height}
+          onBack={() => setActiveSheet('frequency')}
+          onFinish={() => setActiveSheet(null)}
+        />
+      </BottomSheetSwitcher>
+    </>
+  );
+}
+
+export default function BottomSheetSwitcherShowcase() {
+  return <MultiStepSwitcherExample height="hug" />;
+}

package/authoring/doctypes/base/type.ts

@@ -117,6 +117,15 @@ export interface ComponentPlaygroundConfig {
    *  the component is visible on load and knobs stay usable, whereas a real
    *  top-layer modal makes the rest of the page inert (#3657). */
   overlay?: boolean;
+  /** Override the controlled prop and open value used by an overlay preview.
+   *  Use with `overlay: true` when the component does not use `isOpen: true`
+   *  to represent its open state. */
+  overlayControl?: {
+    /** Controlled prop that determines whether the overlay is open. */
+    stateProp: string;
+    /** Value assigned to stateProp when the preview's open button is used. */
+    openValue: unknown;
+  };
   /** The component reads AppShell mobile context and renders nothing
    *  without it (e.g. `MobileNavToggle` returns null unless the context
    *  reports an enabled mobile viewport — the default value outside

package/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);
+});

package/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});

package/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.

package/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');

package/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,

package/package.json

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