@jlcpcb/cli 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jlcpcb/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "CLI for JLC/EasyEDA component sourcing and KiCad library management",
@@ -43,13 +43,13 @@
     "commander": "^12.0.0",
     "ink": "6.6.0",
     "ink-select-input": "6.2.0",
-    "@jlcpcb/core": "workspace:*",
     "open": "11.0.0",
     "react": "^19.0.0",
     "react-devtools-core": "7.0.1",
     "string-width": "^8.2.0"
   },
   "devDependencies": {
+    "@jlcpcb/core": "workspace:*",
     "@types/node": "^20.0.0",
     "@types/react": "19.2.7"
   }

package/src/app/components/ListView.tsx

@@ -33,7 +33,7 @@ export function ListView({
         const row = formatListRow(r, widths);
 
         return (
-          <Box key={r.lcscId}>
+          <Box key={r.id ?? r.lcscId}>
             <Text color="cyan">{isSelected ? '▶' : '  '}</Text>
             {isSelected ? (
               <Text inverse>

package/src/app/components/list-view-format.test.ts

@@ -13,6 +13,8 @@ function createResult(
   overrides: Partial<ComponentSearchResult>
 ): ComponentSearchResult {
   return {
+    id: 'C123',
+    idType: 'lcsc',
     lcscId: 'C123',
     name: 'LM2940CT-5.0/NOPB',
     description:

package/src/app/screens/InfoScreen.tsx

@@ -71,6 +71,7 @@ export function InfoScreen() {
 
   // Get datasheet URL (different field names in different types)
   const datasheetUrl = component && ('datasheetPdf' in component ? component.datasheetPdf : 'datasheet' in component ? component.datasheet : undefined);
+  const componentLcscId = component?.lcscId ?? params.componentId;
 
   const [isRegenerating, setIsRegenerating] = useState(false);
   const [isDeleting, setIsDeleting] = useState(false);
@@ -82,11 +83,11 @@ export function InfoScreen() {
     const lowerInput = input.toLowerCase();
 
     // R - Regenerate symbol and footprint
-    if (lowerInput === 'r' && installedInfo) {
+    if (lowerInput === 'r' && installedInfo && componentLcscId) {
       setIsRegenerating(true);
       setRegenerateMessage('Regenerating symbol and footprint...');
 
-      libraryService.install(component.lcscId, { force: true })
+      libraryService.install(componentLcscId, { force: true })
         .then((result) => {
           setRegenerateMessage(`✓ Regenerated: ${result.symbolAction}`);
           // Clear message after 2 seconds
@@ -127,6 +128,12 @@ export function InfoScreen() {
 
     // Enter - Install (only when not installed)
     if (key.return && !installedInfo) {
+      if (!componentLcscId) {
+        setRegenerateMessage('✗ Missing LCSC part number');
+        setTimeout(() => setRegenerateMessage(null), 3000);
+        return;
+      }
+
       if (checkingRef.current) return;
       checkingRef.current = true;
       setIsCheckingLibrary(true);
@@ -134,7 +141,7 @@ export function InfoScreen() {
       if (libraryStatus && (!libraryStatus.installed || !libraryStatus.linked)) {
         // Libraries not set up - show setup screen
         push('library-setup', {
-          componentId: component.lcscId,
+          componentId: componentLcscId,
           component,
         });
         setIsCheckingLibrary(false);
@@ -142,7 +149,7 @@ export function InfoScreen() {
       } else {
         // Libraries ready - proceed to install
         push('install', {
-          componentId: component.lcscId,
+          componentId: componentLcscId,
           component,
         });
         setIsCheckingLibrary(false);
@@ -176,18 +183,27 @@ export function InfoScreen() {
     );
   }
 
+  if (!componentLcscId) {
+    return (
+      <Box flexDirection="column">
+        <Text color="red">✗ Missing LCSC part number</Text>
+        <Text dimColor>Press Esc to go back</Text>
+      </Box>
+    );
+  }
+
   return (
     <Box flexDirection="column">
       <Box marginBottom={1}>
         <Text bold>
-          Component: <Text color="cyan">{component.lcscId}</Text>
+          Component: <Text color="cyan">{componentLcscId}</Text>
           {' '}
           <Text dimColor>({component.name})</Text>
           {installedInfo && <Text color="green"> ✓ Installed</Text>}
         </Text>
       </Box>
       <DetailView
-        component={component}
+        component={{ ...component, lcscId: componentLcscId }}
         terminalWidth={terminalWidth}
         isInstalled={!!installedInfo}
         installedInfo={installedInfo}

package/src/app/screens/InstalledScreen.tsx

@@ -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/SearchScreen.tsx

@@ -26,10 +26,17 @@ export function SearchScreen() {
     } else if (key.downArrow) {
       setSelectedIndex(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,
+        });
+      } else {
+        push('info', {
+          componentId: selected.lcscId ?? selected.id,
+          component: selected,
+        });
+      }
     } else if (key.tab) {
       setIsSearching(true);
       const newFiltered = !isFiltered;

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

@@ -0,0 +1,203 @@
+import { describe, expect, it, mock, spyOn } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+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();
+  });
+
+  it('validate --json has a quiet JSON path before human output', () => {
+    const source = readFileSync(join(import.meta.dir, 'validate.ts'), 'utf-8');
+
+    expect(source).toContain('const spinner = options.json ? null : p.spinner()');
+    expect(source).toContain('printJson({');
+    expect(source.indexOf('if (options.json)')).toBeLessThan(source.indexOf('console.log(chalk.bold'));
+  });
+});

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,10 +104,19 @@ 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
@@ -85,10 +126,18 @@ export async function easyedaInstallCommand(
       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,8 +150,12 @@ 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

package/src/commands/info.ts

@@ -3,10 +3,9 @@
  * Display component details
  */
 
-import * as p from '@clack/prompts';
-import chalk from 'chalk';
 import { createComponentService } from '@jlcpcb/core';
 import { renderApp } from '../app/App.js';
+import { printJson, printJsonError, getErrorMessage } from '../utils/agent-output.js';
 
 const componentService = createComponentService();
 
@@ -17,16 +16,14 @@ interface InfoOptions {
 export async function infoCommand(id: string, options: InfoOptions): Promise<void> {
   // JSON mode - non-interactive output for scripting
   if (options.json) {
-    const spinner = p.spinner();
-    spinner.start(`Fetching component ${id}...`);
-
     try {
       const details = await componentService.getDetails(id);
-      spinner.stop('Component found');
-      console.log(JSON.stringify(details, null, 2));
+      printJson({
+        success: true,
+        component: details,
+      });
     } catch (error) {
-      spinner.stop('Failed to fetch component');
-      p.log.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      printJsonError('component_fetch_failed', getErrorMessage(error), { retryable: true });
       process.exit(1);
     }
     return;

package/src/commands/install.ts

@@ -7,6 +7,7 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { createComponentService, createLibraryService, type SearchOptions } from '@jlcpcb/core';
 import { renderApp } from '../app/App.js';
+import { printJson, printJsonError, getErrorMessage } from '../utils/agent-output.js';
 
 const componentService = createComponentService();
 const libraryService = createLibraryService();
@@ -19,21 +20,39 @@ function isLcscId(id: string): boolean {
 interface InstallOptions {
   projectPath?: string;
   include3d?: boolean;
+  yes?: boolean;
+  json?: boolean;
   force?: boolean;
 }
 
 export async function installCommand(id: string | undefined, options: InstallOptions): Promise<void> {
+  if (!id && (options.yes || options.json)) {
+    if (options.json) {
+      printJsonError('missing_id', 'Direct install requires an LCSC part number');
+    } else {
+      p.log.error('Direct install requires an LCSC part number.');
+    }
+    process.exit(1);
+  }
+
   // Check if ID looks like an EasyEDA UUID (not an LCSC ID)
   if (id && !isLcscId(id)) {
+    if (options.json) {
+      printJsonError('invalid_lcsc_id', `"${id}" is not an LCSC part number`, {
+        details: { hint: `Use jlc easyeda install ${id}` },
+      });
+      process.exit(1);
+    }
+
     p.log.error(`"${id}" is not an LCSC part number (e.g., C2040).`);
     p.log.info(`For EasyEDA community components, use: ${chalk.cyan(`jlc easyeda install ${id}`)}`);
     process.exit(1);
   }
 
-  // If ID provided with --force, do direct install (non-interactive)
-  if (id && options.force) {
-    const spinner = p.spinner();
-    spinner.start(`Installing component ${id}...`);
+  // If ID provided with --yes or --json, do direct install (non-interactive).
+  if (id && (options.yes || options.json)) {
+    const spinner = options.json ? null : p.spinner();
+    spinner?.start(`Installing component ${id}...`);
 
     try {
       // Ensure libraries are set up
@@ -43,10 +62,18 @@ export async function installCommand(id: string | undefined, options: InstallOpt
       const result = await libraryService.install(id, {
         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();
@@ -59,8 +86,12 @@ export async function installCommand(id: string | undefined, options: InstallOpt
       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('install_failed', getErrorMessage(error), { retryable: true });
+      } else {
+        p.log.error(`Error: ${getErrorMessage(error)}`);
+      }
       process.exit(1);
     }
     return;

package/src/commands/library.ts

@@ -7,6 +7,7 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { createLibraryService, type InstalledComponent } from '@jlcpcb/core';
 import { renderApp } from '../app/App.js';
+import { printJson, printJsonError, getErrorMessage } from '../utils/agent-output.js';
 
 const libraryService = createLibraryService();
 
@@ -17,36 +18,25 @@ interface LibraryOptions {
 export async function libraryCommand(options: LibraryOptions): Promise<void> {
   // JSON mode - non-interactive output for scripting
   if (options.json) {
-    const spinner = p.spinner();
-    spinner.start('Loading library status...');
-
     try {
       const [status, components] = await Promise.all([
         libraryService.getStatus(),
         libraryService.listInstalled({}),
       ]);
 
-      spinner.stop(`Found ${components.length} installed components`);
-
-      console.log(
-        JSON.stringify(
-          {
-            status: {
-              installed: status.installed,
-              linked: status.linked,
-              version: status.version,
-              componentCount: status.componentCount,
-              paths: status.paths,
-            },
-            components,
-          },
-          null,
-          2
-        )
-      );
+      printJson({
+        success: true,
+        status: {
+          installed: status.installed,
+          linked: status.linked,
+          version: status.version,
+          componentCount: status.componentCount,
+          paths: status.paths,
+        },
+        components,
+      });
     } catch (error) {
-      spinner.stop('Failed to get library status');
-      p.log.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      printJsonError('library_status_failed', getErrorMessage(error), { retryable: false });
       process.exit(1);
     }
     return;