@jlcpcb/cli 0.4.0 → 0.4.1

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,58 +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]) {
       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

@@ -1,6 +1,4 @@
 import { describe, expect, it, mock, spyOn } from 'bun:test';
-import { readFileSync } from 'fs';
-import { join } from 'path';
 
 const mockDetails = {
   lcscId: 'C123',
@@ -193,11 +191,4 @@ describe('agent JSON CLI output', () => {
     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

@@ -120,7 +120,7 @@ export async function easyedaInstallCommand(
 
     try {
       // Ensure libraries are set up
-      await libraryService.ensureGlobalTables()
+      if (!options.projectPath) await libraryService.ensureGlobalTables()
 
       // Install the component
       const result = await libraryService.install(uuid, {
@@ -161,10 +161,10 @@ export async function easyedaInstallCommand(
     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
   }
 
@@ -198,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 })
 }

package/src/commands/failures.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+function run(scenario: string) {
+  // Isolate module mocks and process.exit from other CLI/core tests.
+  return spawnSync(process.execPath, [join(import.meta.dir, '__fixtures__/failure-scenarios.ts'), scenario], {
+    encoding: 'utf8',
+    timeout: 15_000,
+  });
+}
+
+describe('command failure exit status', () => {
+  it('reports failed regenerations and exits unsuccessfully', () => {
+    const result = run('regenerate');
+    expect(result.status).toBe(1);
+    expect(result.stdout).toContain('C123');
+    expect(result.stdout).toContain('conversion failed');
+  });
+
+  it('does not pass absent requested reference SVGs in JSON', () => {
+    const result = run('missing');
+    expect(result.status).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      success: false,
+      result: { passed: false, error: expect.stringContaining('footprint, symbol') },
+    });
+  });
+
+  it('reports absent requested references in text', () => {
+    const result = run('text-missing');
+    expect(result.status).toBe(1);
+    expect(result.stdout).toContain('Missing reference SVG: footprint, symbol');
+  });
+
+  it('counts missing references as batch errors instead of passes', () => {
+    const result = run('batch-missing');
+    expect(result.status).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      success: false,
+      summary: { total: 1, passed: 0, failed: 0, errors: 1 },
+    });
+  });
+
+  it('allows an absent footprint reference when its check was disabled', () => {
+    const result = run('disabled-footprint');
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      success: true,
+      result: { passed: true, footprint: null, symbol: { passed: true } },
+    });
+  });
+
+  it('rejects symbol pin displacement through the real comparator', () => {
+    const result = run('symbol-moved');
+    expect(result.status).toBe(1);
+    const output = JSON.parse(result.stdout);
+    expect(output.success).toBe(false);
+    expect(output.result.symbol.errors.some((e: { field: string }) => e.field === 'position')).toBe(true);
+  });
+
+  it('does not pass symbol pins with unknown reference direction', () => {
+    const result = run('symbol-unverified');
+    expect(result.status).toBe(1);
+    const output = JSON.parse(result.stdout);
+    expect(output.success).toBe(false);
+    expect(output.result.symbol.errors.some((e: { field: string }) => e.field === 'coverage')).toBe(true);
+  });
+
+  it('rejects a manufacturing position mismatch through the real comparator', () => {
+    const result = run('footprint-moved');
+    expect(result.status).toBe(1);
+    const output = JSON.parse(result.stdout);
+    expect(output.success).toBe(false);
+    expect(output.result.footprint.errors.some((e: { field: string }) => e.field === 'position')).toBe(true);
+  });
+
+  it('does not claim success for an unverified reference copper layer', () => {
+    const result = run('footprint-unverified');
+    expect(result.status).toBe(1);
+    const output = JSON.parse(result.stdout);
+    expect(output.success).toBe(false);
+    expect(output.result.footprint.errors.some((e: { field: string }) => e.field === 'coverage')).toBe(true);
+  });
+
+  it('validates matching, fully described manufacturing geometry', () => {
+    const result = run('footprint-matching');
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      success: true,
+      result: { passed: true, footprint: { passed: true, errors: [] } },
+    });
+  });
+
+  it.each(['mpn', 'package'])('rejects a changed fixture %s during batch validation', (field) => {
+    const result = run(`footprint-identity-${field}`);
+    expect(result.status).toBe(1);
+    const output = JSON.parse(result.stdout);
+    expect(output).toMatchObject({
+      success: false,
+      summary: { total: 1, passed: 0, failed: 0, errors: 1 },
+    });
+    expect(output.results[0].error).toMatch(field === 'mpn' ? /Fixture MPN differs/ : /Fixture package differs/);
+  });
+});

package/src/commands/install.ts

@@ -56,7 +56,7 @@ export async function installCommand(id: string | undefined, options: InstallOpt
 
     try {
       // Ensure libraries are set up
-      await libraryService.ensureGlobalTables();
+      if (!options.projectPath) await libraryService.ensureGlobalTables();
 
       // Install the component
       const result = await libraryService.install(id, {
@@ -97,7 +97,7 @@ export async function installCommand(id: string | undefined, options: InstallOpt
     return;
   }
 
-  // If ID provided (without --force), fetch component and launch TUI for install
+  // If ID provided, fetch component and launch TUI for install.
   if (id) {
     console.log(`Fetching component ${id}...`);
 
@@ -105,7 +105,7 @@ export async function installCommand(id: string | undefined, options: InstallOpt
       const details = await componentService.getDetails(id);
       // Clear the "Fetching..." line and launch interactive UI
       process.stdout.write('\x1b[1A\x1b[2K');
-      await renderApp('info', { componentId: id, component: details as any });
+      await renderApp('info', { componentId: id, component: details, installOptions: options });
     } catch (error) {
       console.error(`Failed to fetch component: ${error instanceof Error ? error.message : 'Unknown error'}`);
       process.exit(1);
@@ -147,5 +147,5 @@ export async function installCommand(id: string | undefined, options: InstallOpt
 
   // 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 });
 }

package/src/commands/interactive-install.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+describe('interactive install artifacts', () => {
+  for (const [scenario, behavior] of [
+    ['lcsc', 'reinstalls the selected LCSC project artifact with downloaded 3D bytes through no-ID search'],
+    ['community', 'ignores global community installation status and installs/reinstalls locally without 3D through no-ID search'],
+  ]) {
+    it(behavior, () => {
+      // Core services and Ink are real; only upstream clients and terminal/prompt IO are substituted.
+      const root = mkdtempSync(join(tmpdir(), 'jlc-interactive-install-'));
+      try {
+        const result = spawnSync(process.execPath, [
+          join(import.meta.dir, '../app/__fixtures__/interactive-install-scenarios.tsx'), scenario, root,
+        ], {
+          encoding: 'utf8',
+          timeout: 15_000,
+          env: { ...process.env, HOME: join(root, 'home'), USERPROFILE: join(root, 'home'), XDG_CONFIG_HOME: join(root, 'config') },
+        });
+        expect({ status: result.status, stderr: result.stderr }).toEqual({ status: 0, stderr: '' });
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    }, 20_000);
+  }
+});

package/src/commands/library.ts

@@ -91,5 +91,6 @@ export async function regenerateCommand(options: RegenerateOptions): Promise<voi
     for (const comp of result.components.filter(c => c.status === 'failed')) {
       console.log(chalk.red(`  • ${comp.name} (${comp.id}): ${comp.error}`));
     }
+    process.exitCode = 1;
   }
 }

package/src/commands/search.ts

@@ -58,7 +58,7 @@ export async function searchCommand(query: string, options: SearchCommandOptions
 
     // Clear the "Searching..." line and launch interactive UI
     process.stdout.write('\x1b[1A\x1b[2K');
-    await renderApp('search', { query, results });
+    await renderApp('search', { query, results, searchOptions: options });
   } catch (error) {
     if (options.json) {
       printJsonError('search_failed', getErrorMessage(error), { retryable: true });

package/src/commands/validate.ts

@@ -18,7 +18,6 @@ import {
   formatSymbolComparisonResult,
   generateValidationReport,
   generateBatchReport,
-  TEST_CATEGORIES,
   getAllTestComponents,
   getTestComponentsByCategory,
   getCategoryNames,
@@ -26,6 +25,7 @@ import {
   renderSymbolSvg,
   type ValidationResult,
   type ReportSvgs,
+  type TestComponent,
   easyedaClient,
   footprintConverter,
   symbolConverter,
@@ -46,7 +46,8 @@ interface ValidateOptions {
  */
 async function validateComponent(
   lcscCode: string,
-  options: { footprint: boolean; symbol: boolean }
+  options: { footprint: boolean; symbol: boolean },
+  identity?: Pick<TestComponent, 'expectedMpn' | 'expectedPackage'>
 ): Promise<ValidationResult> {
   const startTime = Date.now();
   const normalizedCode = lcscCode.replace(/^C/i, '');
@@ -70,9 +71,18 @@ async function validateComponent(
         error: 'Failed to fetch component data from EasyEDA',
       };
     }
+    if (identity?.expectedMpn !== undefined && componentData.info.name !== identity.expectedMpn) {
+      throw new Error(`Fixture MPN differs: expected ${identity.expectedMpn}, got ${componentData.info.name}`);
+    }
+    if (identity?.expectedPackage !== undefined && componentData.footprint.name !== identity.expectedPackage) {
+      throw new Error(`Fixture package differs: expected ${identity.expectedPackage}, got ${componentData.footprint.name}`);
+    }
 
     let footprintResult = null;
     let symbolResult = null;
+    const missingReferences: string[] = [];
+    if (options.footprint && !reference.footprintSvg) missingReferences.push('footprint');
+    if (options.symbol && !reference.symbolSvg) missingReferences.push('symbol');
 
     // Validate footprint
     if (options.footprint && reference.footprintSvg) {
@@ -81,10 +91,7 @@ async function validateComponent(
       const refData = extractFromReferenceSVG(reference.footprintSvg);
       const genData = extractFromKiCadFootprint(kicadContent);
 
-      footprintResult = compareFootprints(refData, genData, {
-        sizeWarningsOnly: true,
-        positionTolerance: 50,
-      });
+      footprintResult = compareFootprints(refData, genData);
     }
 
     // Validate symbol
@@ -96,12 +103,11 @@ async function validateComponent(
       const refData = extractSymbolFromReferenceSVG(reference.symbolSvg);
       const genData = extractFromKiCadSymbol(kicadContent);
 
-      symbolResult = compareSymbols(refData, genData, {
-        positionTolerance: 50,
-      });
+      symbolResult = compareSymbols(refData, genData);
     }
 
     const passed =
+      missingReferences.length === 0 &&
       (!footprintResult || footprintResult.passed) && (!symbolResult || symbolResult.passed);
 
     return {
@@ -112,6 +118,9 @@ async function validateComponent(
       symbol: symbolResult,
       timestamp: new Date(),
       durationMs: Date.now() - startTime,
+      ...(missingReferences.length > 0
+        ? { error: `Missing reference SVG: ${missingReferences.join(', ')}` }
+        : {}),
     };
   } catch (error) {
     return {
@@ -287,13 +296,13 @@ export async function validateCommand(
     const result = await validateComponent(component.lcsc, {
       footprint: validateFootprint,
       symbol: validateSymbol,
-    });
+    }, component);
 
     results.push(result);
 
     if (result.error) {
       errors++;
-      if (!options.json) console.log(chalk.yellow('⚠ ERROR'));
+      if (!options.json) console.log(chalk.yellow(`ERROR: ${result.error}`));
     } else if (result.passed) {
       passed++;
       if (!options.json) console.log(chalk.green('✓ PASS'));