@jlcpcb/cli 0.3.2 → 0.4.1

package/src/app/screens/InstallScreen.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect } from 'react';
 import { Box, Text } from 'ink';
 import { createLibraryService, type InstallResult } from '@jlcpcb/core';
 import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
@@ -10,14 +10,12 @@ export function InstallScreen() {
   const { replace } = useNavigation();
   const { params } = useCurrentScreen() as { screen: 'install'; params: InstallParams };
 
-  const [status, setStatus] = useState<'installing' | 'done'>('installing');
-
   useEffect(() => {
     let mounted = true;
 
     async function install() {
       try {
-        const result: InstallResult = await libraryService.install(params.componentId, {});
+        const result: InstallResult = await libraryService.install(params.componentId, params.installOptions);
         if (mounted) {
           replace('installed', {
             componentId: params.componentId,
@@ -41,7 +39,7 @@ export function InstallScreen() {
     return () => {
       mounted = false;
     };
-  }, [params.componentId, params.component, replace]);
+  }, [params.componentId, params.component, params.installOptions, replace]);
 
   return (
     <Box flexDirection="column">

package/src/app/screens/InstalledScreen.tsx

@@ -10,8 +10,8 @@ export function InstalledScreen() {
   const { params } = useCurrentScreen() as { screen: 'installed'; params: InstalledParams };
   const { columns: terminalWidth } = useTerminalSize();
 
-  useInput(() => {
-    pop();
+  useInput((_input, key) => {
+    if (!key.escape) pop();
   });
 
   const result = params.result
@@ -29,7 +29,7 @@ export function InstalledScreen() {
         </Text>
       </Box>
       <InstalledView
-        component={params.component}
+        component={{ ...params.component, lcscId: params.componentId }}
         result={result}
         error={params.error || null}
         terminalWidth={terminalWidth}

package/src/app/screens/LibrarySetupScreen.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { createLibraryService } from '@jlcpcb/core';
 import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
@@ -9,13 +9,19 @@ import { Divider } from '../components/Divider.js';
 const libraryService = createLibraryService();
 
 export function LibrarySetupScreen() {
-  const { push, pop } = useNavigation();
+  const { replace, pop } = useNavigation();
   const { params } = useCurrentScreen() as { screen: 'library-setup'; params: LibrarySetupParams };
   const { columns: terminalWidth } = useTerminalSize();
 
   const [selectedOption, setSelectedOption] = useState<'install' | 'cancel'>('install');
   const [isInstalling, setIsInstalling] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const activeRef = useRef(true);
+
+  useEffect(() => {
+    activeRef.current = true;
+    return () => { activeRef.current = false; };
+  }, []);
 
   useInput((input, key) => {
     if (isInstalling) return;
@@ -31,19 +37,20 @@ export function LibrarySetupScreen() {
         libraryService
           .ensureGlobalTables()
           .then(() => {
+            if (!activeRef.current) return;
             // Success - continue to install the component
-            push('install', {
+            replace('install', {
               componentId: params.componentId,
               component: params.component,
+              installOptions: params.installOptions,
             });
           })
           .catch((err) => {
+            if (!activeRef.current) return;
             setError(err instanceof Error ? err.message : 'Unknown error');
             setIsInstalling(false);
           });
       }
-    } else if (key.escape) {
-      pop();
     }
   });
 

package/src/app/screens/SearchScreen.tsx

@@ -1,51 +1,55 @@
 import React, { useState } from 'react';
 import { Box, Text, useInput } from 'ink';
-import { createComponentService, type ComponentSearchResult } from '@jlcpcb/core';
+import { createComponentService } from '@jlcpcb/core';
 import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
 import type { SearchParams } from '../navigation/types.js';
-import { useAppState } from '../state/AppStateContext.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
 import { ListView } from '../components/ListView.js';
 
 const componentService = createComponentService();
 
 export function SearchScreen() {
-  const { push } = useNavigation();
+  const { push, replace } = useNavigation();
   const { params } = useCurrentScreen() as { screen: 'search'; params: SearchParams };
-  const { selectedIndex, setSelectedIndex, isFiltered, setIsFiltered, resetSelection } = useAppState();
   const { columns: terminalWidth } = useTerminalSize();
 
-  const [results, setResults] = useState<ComponentSearchResult[]>(params.results);
+  const { results, selectedIndex = 0 } = params;
+  const isFiltered = params.searchOptions?.basicOnly ?? false;
   const [isSearching, setIsSearching] = useState(false);
 
   useInput(async (input, key) => {
     if (isSearching) return;
 
     if (key.upArrow) {
-      setSelectedIndex(Math.max(0, selectedIndex - 1));
+      replace('search', { ...params, selectedIndex: Math.max(0, selectedIndex - 1) });
     } else if (key.downArrow) {
-      setSelectedIndex(Math.min(results.length - 1, selectedIndex + 1));
+      replace('search', { ...params, selectedIndex: Math.max(0, Math.min(results.length - 1, selectedIndex + 1)) });
     } else if (key.return && results[selectedIndex]) {
-      push('info', {
-        componentId: results[selectedIndex].lcscId,
-        component: results[selectedIndex],
-      });
+      const selected = results[selectedIndex];
+      if (selected.idType === 'easyeda_uuid') {
+        push('easyeda-info', {
+          uuid: selected.easyedaUuid ?? selected.id,
+          installOptions: params.installOptions,
+        });
+      } else {
+        push('info', {
+          componentId: selected.lcscId ?? selected.id,
+          component: selected,
+          installOptions: params.installOptions,
+        });
+      }
     } else if (key.tab) {
       setIsSearching(true);
       const newFiltered = !isFiltered;
       try {
-        let newResults = await componentService.search(params.query, {
-          limit: 20,
-          basicOnly: newFiltered,
-        });
+        const searchOptions = { ...params.searchOptions, basicOnly: newFiltered };
+        let newResults = await componentService.search(params.query, searchOptions);
         newResults = newResults.sort((a, b) => {
           if (a.libraryType === 'basic' && b.libraryType !== 'basic') return -1;
           if (a.libraryType !== 'basic' && b.libraryType === 'basic') return 1;
           return 0;
         });
-        setResults(newResults);
-        resetSelection();
-        setIsFiltered(newFiltered);
+        replace('search', { ...params, results: newResults, searchOptions, selectedIndex: 0 });
       } catch {
         // Keep existing results on error
       }

package/src/app/state/AppStateContext.tsx

@@ -2,15 +2,10 @@ import React, { createContext, useContext, useState, useCallback, type ReactNode
 
 export interface AppState {
   selectedIndex: number;
-  isFiltered: boolean;
-  isLoading: boolean;
 }
 
 export interface AppStateActions {
   setSelectedIndex: (index: number) => void;
-  setIsFiltered: (filtered: boolean) => void;
-  setIsLoading: (loading: boolean) => void;
-  resetSelection: () => void;
 }
 
 export type AppStateContextValue = AppState & AppStateActions;
@@ -23,33 +18,15 @@ interface AppStateProviderProps {
 
 export function AppStateProvider({ children }: AppStateProviderProps) {
   const [selectedIndex, setSelectedIndexState] = useState(0);
-  const [isFiltered, setIsFilteredState] = useState(false);
-  const [isLoading, setIsLoadingState] = useState(false);
 
   const setSelectedIndex = useCallback((index: number) => {
     setSelectedIndexState(index);
   }, []);
 
-  const setIsFiltered = useCallback((filtered: boolean) => {
-    setIsFilteredState(filtered);
-  }, []);
-
-  const setIsLoading = useCallback((loading: boolean) => {
-    setIsLoadingState(loading);
-  }, []);
-
-  const resetSelection = useCallback(() => {
-    setSelectedIndexState(0);
-  }, []);
 
   const value: AppStateContextValue = {
     selectedIndex,
-    isFiltered,
-    isLoading,
     setSelectedIndex,
-    setIsFiltered,
-    setIsLoading,
-    resetSelection,
   };
 
   return <AppStateContext.Provider value={value}>{children}</AppStateContext.Provider>;

package/src/commands/__fixtures__/failure-scenarios.ts

@@ -0,0 +1,67 @@
+import { mock } from 'bun:test';
+import * as core from '@jlcpcb/core';
+
+const scenario = process.argv[2];
+const manufacturing = scenario.startsWith('footprint-');
+const symbolScenario = scenario === 'disabled-footprint' || scenario.startsWith('symbol-');
+const symbolReference = `<svg>
+  <g c_partid="part_pin" c_spicepin="1" c_origin="-10,0" c_elec="1" ${scenario === 'symbol-unverified' ? '' : 'c_rotation="180"'}>
+    ${scenario === 'symbol-unverified' ? '' : '<path d="M-10,0h5"/>'}<text>IN</text><text>1</text>
+  </g>
+  <g c_partid="part_pin" c_spicepin="2" c_origin="10,0" c_elec="2" c_rotation="0">
+    <path d="M10,0h-5"/><text>OUT</text><text>2</text>
+  </g>
+</svg>`;
+const reference = manufacturing
+  ? {
+    footprintSvg: `<svg><g c_partid="part_pad" number="1" c_origin="0,0" ${scenario === 'footprint-unverified' ? '' : 'layerid="1"'}>
+      <rect x="-2" y="-1" width="4" height="2" />
+      <circle c_padhole="1" cx="0" cy="0" r="0" />
+    </g></svg>`,
+    symbolSvg: null,
+  }
+  : symbolScenario
+    ? { footprintSvg: null, symbolSvg: symbolReference }
+    : { footprintSvg: null, symbolSvg: null };
+
+mock.module('@jlcpcb/core', () => ({
+  ...core,
+  fetchReferenceSVG: async () => reference,
+  easyedaClient: { getComponentData: async () => ({
+    info: { name: scenario === 'footprint-identity-mpn' ? 'DifferentPart' : 'Part' },
+    footprint: { name: scenario === 'footprint-identity-package' ? 'DifferentPackage' : 'PKG' },
+  }) },
+  footprintConverter: {
+    convert: () => `(footprint "Part" (pad "1" smd rect (at ${scenario === 'footprint-moved' ? 4 : 0} 0) (size 1.016 0.508) (layers "F.Cu")))`,
+  },
+  symbolConverter: {
+    convert: () => `(symbol "Part" (symbol "Part_1_1"
+      (pin input line (at -2.54 0 0) (length 1.27) (name "IN") (number "1"))
+      (pin output line (at ${scenario === 'symbol-moved' ? 4.54 : 2.54} 0 180) (length 1.27) (name "OUT") (number "2"))))`,
+  },
+  getAllTestComponents: () => [{ lcsc: 'C123', name: 'Part', expectedMpn: 'Part', expectedPackage: 'PKG' }],
+  createLibraryService: () => ({
+    listInstalled: async () => [{ lcscId: 'C123', name: 'Part' }],
+    regenerate: async () => ({
+      total: 1,
+      success: 0,
+      failed: 1,
+      components: [{ id: 'C123', name: 'Part', status: 'failed', error: 'conversion failed' }],
+    }),
+  }),
+}));
+
+// Commands must load after the subprocess-specific dependency mocks.
+if (scenario === 'regenerate') {
+  const { regenerateCommand } = await import('../library.js');
+  await regenerateCommand({});
+} else {
+  const { validateCommand } = await import('../validate.js');
+  const batch = scenario === 'batch-missing' || scenario.startsWith('footprint-identity-');
+  await validateCommand(batch ? undefined : 'C123', {
+    json: scenario !== 'text-missing',
+    all: batch,
+    symbolOnly: symbolScenario,
+    footprintOnly: manufacturing,
+  });
+}

package/src/commands/agent-json.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it, mock, spyOn } from 'bun:test';
+
+const mockDetails = {
+  lcscId: 'C123',
+  name: 'Part',
+  manufacturer: 'Maker',
+  description: 'A part',
+  category: 'ICs',
+  package: 'SOT-23',
+  pinCount: 3,
+  padCount: 3,
+  has3DModel: false,
+};
+
+const mockSearchResults = [{
+  id: 'C123',
+  idType: 'lcsc' as const,
+  lcscId: 'C123',
+  name: 'Part',
+  manufacturer: 'Maker',
+  description: 'A part',
+  package: 'SOT-23',
+  stock: 10,
+}];
+
+const mockInstallResult = {
+  success: true,
+  id: 'C123',
+  source: 'lcsc' as const,
+  storageMode: 'global' as const,
+  category: 'ICs',
+  symbolName: 'Part',
+  symbolRef: 'JLC-MCP-ICs:Part',
+  footprintRef: 'Package:SOT-23',
+  footprintType: 'reference' as const,
+  files: {
+    symbolLibrary: '/tmp/symbols/JLC-MCP-ICs.kicad_sym',
+  },
+  symbolAction: 'exists' as const,
+  validationData: {
+    component: { name: 'Part' },
+    symbol: { pin_count: 3, pins: [] },
+    footprint: {
+      type: 'smd',
+      pad_count: 3,
+      pads: null,
+      is_kicad_standard: true,
+      kicad_ref: 'Package:SOT-23',
+    },
+    checks: {
+      pin_pad_count_match: true,
+      has_power_pins: false,
+      has_ground_pins: false,
+    },
+  },
+};
+
+mock.module('@jlcpcb/core', () => ({
+  createComponentService: () => ({
+    getDetails: async () => mockDetails,
+    search: async () => mockSearchResults,
+  }),
+  createLibraryService: () => ({
+    ensureGlobalTables: async () => undefined,
+    install: async () => mockInstallResult,
+    getStatus: async () => ({
+      installed: true,
+      linked: true,
+      version: '9.0',
+      componentCount: 1,
+      paths: {
+        symbolsDir: '/tmp/symbols',
+        footprintsDir: '/tmp/footprints',
+        models3dDir: '/tmp/models',
+        symLibTable: '/tmp/sym-lib-table',
+        fpLibTable: '/tmp/fp-lib-table',
+      },
+    }),
+    listInstalled: async () => [{
+      lcscId: 'C123',
+      name: 'Part',
+      category: 'ICs',
+      symbolRef: 'JLC-MCP-ICs:Part',
+      footprintRef: 'Package:SOT-23',
+      library: 'JLC-MCP-ICs',
+      has3dModel: false,
+    }],
+  }),
+  startHttpServer: () => 3847,
+  stopHttpServer: () => undefined,
+}));
+
+describe('agent JSON CLI output', () => {
+  it('info --json writes only a JSON object', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { infoCommand } = await import('./info.js');
+
+    await infoCommand('C123', { json: true });
+
+    expect(write).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(String(write.mock.calls[0][0]))).toEqual({
+      success: true,
+      component: mockDetails,
+    });
+    write.mockRestore();
+  });
+
+  it('search --json writes only a JSON object and does not require the TUI', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { searchCommand } = await import('./search.js');
+
+    await searchCommand('part', { json: true, limit: 1, source: 'lcsc' });
+
+    const payload = JSON.parse(String(write.mock.calls[0][0]));
+    expect(payload).toMatchObject({
+      success: true,
+      query: 'part',
+      count: 1,
+      results: [{
+        id: 'C123',
+        id_type: 'lcsc',
+        lcsc_id: 'C123',
+        name: 'Part',
+      }],
+    });
+    expect(write).toHaveBeenCalledTimes(1);
+    write.mockRestore();
+  });
+
+  it('library status --json writes only a JSON object', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { libraryCommand } = await import('./library.js');
+
+    await libraryCommand({ json: true });
+
+    const payload = JSON.parse(String(write.mock.calls[0][0]));
+    expect(payload.success).toBe(true);
+    expect(payload.status.installed).toBe(true);
+    expect(payload.components).toHaveLength(1);
+    expect(write).toHaveBeenCalledTimes(1);
+    write.mockRestore();
+  });
+
+  it('install --json writes only a JSON object and does not require --force', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { installCommand } = await import('./install.js');
+
+    await installCommand('C123', { json: true });
+
+    const payload = JSON.parse(String(write.mock.calls[0][0]));
+    expect(payload).toMatchObject({
+      success: true,
+      result: {
+        id: 'C123',
+        symbolAction: 'exists',
+      },
+    });
+    expect(write).toHaveBeenCalledTimes(1);
+    write.mockRestore();
+  });
+
+  it('easyeda search --json writes normalized search results', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { easyedaSearchCommand } = await import('./easyeda.js');
+
+    await easyedaSearchCommand('part', { json: true });
+
+    const payload = JSON.parse(String(write.mock.calls[0][0]));
+    expect(payload.results[0]).toMatchObject({
+      id: 'C123',
+      id_type: 'lcsc',
+    });
+    expect(write).toHaveBeenCalledTimes(1);
+    write.mockRestore();
+  });
+
+  it('easyeda install --json writes only a JSON object and does not require --force', async () => {
+    const write = spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const { easyedaInstallCommand } = await import('./easyeda.js');
+
+    await easyedaInstallCommand('8007c710c0b9406db963b55df6990340', { json: true });
+
+    const payload = JSON.parse(String(write.mock.calls[0][0]));
+    expect(payload).toMatchObject({
+      success: true,
+      result: {
+        symbolRef: 'JLC-MCP-ICs:Part',
+      },
+    });
+    expect(write).toHaveBeenCalledTimes(1);
+    write.mockRestore();
+  });
+
+});

package/src/commands/easyeda.ts

@@ -14,12 +14,17 @@ import {
   type SearchOptions,
 } from '@jlcpcb/core'
 import { renderApp } from '../app/App.js'
+import { printJson, printJsonError, getErrorMessage } from '../utils/agent-output.js'
+import { formatSearchResultForJson } from '../utils/search-result-output.js'
 
 const componentService = createComponentService()
 const libraryService = createLibraryService()
 
 interface EasyedaSearchOptions {
   port?: number
+  json?: boolean
+  open?: boolean
+  once?: boolean
 }
 
 /**
@@ -29,6 +34,25 @@ export async function easyedaSearchCommand(
   query: string,
   options: EasyedaSearchOptions
 ): Promise<void> {
+  if (options.json) {
+    try {
+      const results = await componentService.search(query, {
+        limit: 20,
+        source: 'easyeda-community',
+      })
+      printJson({
+        success: true,
+        query,
+        count: results.length,
+        results: results.map(formatSearchResultForJson),
+      })
+    } catch (error) {
+      printJsonError('easyeda_search_failed', getErrorMessage(error), { retryable: true })
+      process.exit(1)
+    }
+    return
+  }
+
   const port = options.port ?? 3847
 
   console.log('Starting component browser...')
@@ -41,8 +65,14 @@ export async function easyedaSearchCommand(
 
       console.log(`Browser opened at ${searchUrl}`)
 
-      // Open browser
-      await open(searchUrl)
+      if (options.open !== false) {
+        await open(searchUrl)
+      }
+
+      if (options.once) {
+        stopHttpServer()
+        process.exit(0)
+      }
 
       console.log('Press Ctrl+C to stop the server and exit')
     }
@@ -62,6 +92,8 @@ export async function easyedaSearchCommand(
 interface EasyedaInstallOptions {
   projectPath?: string
   include3d?: boolean
+  yes?: boolean
+  json?: boolean
   force?: boolean
 }
 
@@ -72,23 +104,40 @@ export async function easyedaInstallCommand(
   uuid: string | undefined,
   options: EasyedaInstallOptions
 ): Promise<void> {
-  // If UUID provided with --force, do direct install (non-interactive)
-  if (uuid && options.force) {
-    const spinner = p.spinner()
-    spinner.start(`Installing EasyEDA component ${uuid}...`)
+  if (!uuid && (options.yes || options.json)) {
+    if (options.json) {
+      printJsonError('missing_uuid', 'Direct EasyEDA install requires a component UUID')
+    } else {
+      p.log.error('Direct EasyEDA install requires a component UUID.')
+    }
+    process.exit(1)
+  }
+
+  // If UUID provided with --yes or --json, do direct install (non-interactive)
+  if (uuid && (options.yes || options.json)) {
+    const spinner = options.json ? null : p.spinner()
+    spinner?.start(`Installing EasyEDA component ${uuid}...`)
 
     try {
       // Ensure libraries are set up
-      await libraryService.ensureGlobalTables()
+      if (!options.projectPath) await libraryService.ensureGlobalTables()
 
       // Install the component
       const result = await libraryService.install(uuid, {
         projectPath: options.projectPath,
         include3d: options.include3d,
-        force: true,
+        force: options.force,
       })
 
-      spinner.stop(chalk.green('✓ Component installed'))
+      spinner?.stop(chalk.green('✓ Component installed'))
+
+      if (options.json) {
+        printJson({
+          success: true,
+          result,
+        })
+        return
+      }
 
       // Display result
       console.log()
@@ -101,17 +150,21 @@ export async function easyedaInstallCommand(
       console.log()
       console.log(chalk.dim(`Library: ${result.files.symbolLibrary}`))
     } catch (error) {
-      spinner.stop(chalk.red('✗ Installation failed'))
-      p.log.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`)
+      spinner?.stop(chalk.red('✗ Installation failed'))
+      if (options.json) {
+        printJsonError('easyeda_install_failed', getErrorMessage(error), { retryable: true })
+      } else {
+        p.log.error(`Error: ${getErrorMessage(error)}`)
+      }
       process.exit(1)
     }
     return
   }
 
-  // If UUID provided (without --force), launch TUI to fetch and display
+  // If UUID provided, launch TUI to fetch and display.
   if (uuid) {
     // Launch TUI at EasyEDA info screen - let it fetch the component
-    await renderApp('easyeda-info', { uuid })
+    await renderApp('easyeda-info', { uuid, installOptions: options })
     return
   }
 
@@ -145,5 +198,5 @@ export async function easyedaInstallCommand(
 
   // Clear the "Searching..." line and launch interactive UI
   process.stdout.write('\x1b[1A\x1b[2K')
-  await renderApp('search', { query: query as string, results })
+  await renderApp('search', { query: query as string, results, searchOptions, installOptions: options })
 }