@jlcpcb/cli 0.3.2 → 0.4.1

package/src/commands/validate.ts

@@ -18,7 +18,6 @@ import {
   formatSymbolComparisonResult,
   generateValidationReport,
   generateBatchReport,
-  TEST_CATEGORIES,
   getAllTestComponents,
   getTestComponentsByCategory,
   getCategoryNames,
@@ -26,10 +25,12 @@ import {
   renderSymbolSvg,
   type ValidationResult,
   type ReportSvgs,
+  type TestComponent,
   easyedaClient,
   footprintConverter,
   symbolConverter,
 } from '@jlcpcb/core';
+import { printJson, printJsonError } from '../utils/agent-output.js';
 
 interface ValidateOptions {
   footprintOnly?: boolean;
@@ -45,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, '');
@@ -69,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) {
@@ -80,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
@@ -95,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 {
@@ -111,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 {
@@ -130,46 +140,32 @@ export async function validateCommand(
   id: string | undefined,
   options: ValidateOptions
 ): Promise<void> {
+  if (options.footprintOnly && options.symbolOnly) {
+    if (options.json) {
+      printJsonError('invalid_options', '--footprint-only and --symbol-only are mutually exclusive');
+    } else {
+      p.log.error('--footprint-only and --symbol-only are mutually exclusive');
+    }
+    process.exit(1);
+  }
+
   const validateFootprint = !options.symbolOnly;
   const validateSymbol = !options.footprintOnly;
 
   // Single component validation
   if (id && !options.category && !options.all) {
-    const spinner = p.spinner();
-    spinner.start(`Validating ${id}...`);
+    const spinner = options.json ? null : p.spinner();
+    spinner?.start(`Validating ${id}...`);
 
     const result = await validateComponent(id, {
       footprint: validateFootprint,
       symbol: validateSymbol,
     });
 
-    spinner.stop(result.passed ? chalk.green('✓ Validation passed') : chalk.red('✗ Validation failed'));
-
-    // Display results
-    console.log();
-    console.log(chalk.bold(`${result.componentName} (${result.lcscCode})`));
-    console.log(chalk.dim(`Duration: ${result.durationMs}ms`));
-    console.log();
-
-    if (result.error) {
-      console.log(chalk.red(`Error: ${result.error}`));
-      process.exit(1);
-    }
-
-    if (result.footprint) {
-      console.log(formatComparisonResult(result.footprint));
-    }
+    spinner?.stop(result.passed ? chalk.green('✓ Validation passed') : chalk.red('✗ Validation failed'));
 
-    if (result.symbol) {
-      console.log(formatSymbolComparisonResult(result.symbol));
-    }
+    let htmlPath: string | undefined;
 
-    // JSON output
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-    }
-
-    // HTML output
     if (options.html) {
       const reference = await fetchReferenceSVG(id);
       const componentData = await easyedaClient.getComponentData(id);
@@ -195,9 +191,42 @@ export async function validateCommand(
 
       const html = generateValidationReport(result, svgs);
       writeFileSync(options.html, html);
-      console.log(chalk.dim(`HTML report: ${options.html}`));
+      htmlPath = options.html;
     }
 
+    if (options.json) {
+      printJson({
+        success: result.passed && !result.error,
+        result,
+        html: htmlPath,
+      });
+      process.exit(result.passed && !result.error ? 0 : 1);
+    }
+
+    // Display results
+    console.log();
+    console.log(chalk.bold(`${result.componentName} (${result.lcscCode})`));
+    console.log(chalk.dim(`Duration: ${result.durationMs}ms`));
+    console.log();
+
+    if (result.error) {
+      console.log(chalk.red(`Error: ${result.error}`));
+      process.exit(1);
+    }
+
+    if (result.footprint) {
+      console.log(formatComparisonResult(result.footprint));
+    }
+
+    if (result.symbol) {
+      console.log(formatSymbolComparisonResult(result.symbol));
+    }
+
+    if (htmlPath) {
+      console.log(chalk.dim(`HTML report: ${htmlPath}`));
+    }
+
+
     process.exit(result.passed ? 0 : 1);
   }
 
@@ -209,6 +238,11 @@ export async function validateCommand(
       : [];
 
   if (components.length === 0 && !id) {
+    if (options.json) {
+      printJsonError('missing_validation_target', 'JSON validation requires an id, --category, or --all');
+      process.exit(1);
+    }
+
     // Interactive category selection
     const categories = getCategoryNames();
     const selected = await p.select({
@@ -232,11 +266,22 @@ export async function validateCommand(
   components = components.filter((c) => !c.skip);
 
   if (components.length === 0) {
+    if (options.json) {
+      printJson({
+        success: true,
+        summary: { total: 0, passed: 0, failed: 0, errors: 0 },
+        results: [],
+      });
+      process.exit(0);
+    }
+
     p.log.warn('No components to validate');
     process.exit(0);
   }
 
-  console.log(chalk.bold(`\nValidating ${components.length} components...\n`));
+  if (!options.json) {
+    console.log(chalk.bold(`\nValidating ${components.length} components...\n`));
+  }
 
   const results: ValidationResult[] = [];
   let passed = 0;
@@ -244,43 +289,59 @@ export async function validateCommand(
   let errors = 0;
 
   for (const component of components) {
-    process.stdout.write(`  ${component.lcsc.padEnd(12)} ${component.name.slice(0, 40).padEnd(42)} `);
+    if (!options.json) {
+      process.stdout.write(`  ${component.lcsc.padEnd(12)} ${component.name.slice(0, 40).padEnd(42)} `);
+    }
 
     const result = await validateComponent(component.lcsc, {
       footprint: validateFootprint,
       symbol: validateSymbol,
-    });
+    }, component);
 
     results.push(result);
 
     if (result.error) {
       errors++;
-      console.log(chalk.yellow('⚠ ERROR'));
+      if (!options.json) console.log(chalk.yellow(`ERROR: ${result.error}`));
     } else if (result.passed) {
       passed++;
-      console.log(chalk.green('✓ PASS'));
+      if (!options.json) console.log(chalk.green('✓ PASS'));
     } else {
       failed++;
-      console.log(chalk.red('✗ FAIL'));
+      if (!options.json) console.log(chalk.red('✗ FAIL'));
     }
   }
 
+  let htmlPath: string | undefined;
+  if (options.html) {
+    const html = generateBatchReport(results, 'JLC-CLI Validation Report');
+    writeFileSync(options.html, html);
+    htmlPath = options.html;
+  }
+
+  if (options.json) {
+    printJson({
+      success: failed === 0 && errors === 0,
+      summary: {
+        total: results.length,
+        passed,
+        failed,
+        errors,
+      },
+      results,
+      html: htmlPath,
+    });
+    process.exit(failed > 0 || errors > 0 ? 1 : 0);
+  }
+
   // Summary
   console.log();
   console.log(chalk.bold('Summary:'));
   console.log(`  ${chalk.green(`${passed} passed`)}  ${chalk.red(`${failed} failed`)}  ${chalk.yellow(`${errors} errors`)}`);
   console.log();
 
-  // JSON output
-  if (options.json) {
-    console.log(JSON.stringify(results, null, 2));
-  }
-
-  // HTML output
-  if (options.html) {
-    const html = generateBatchReport(results, 'JLC-CLI Validation Report');
-    writeFileSync(options.html, html);
-    console.log(chalk.dim(`HTML report: ${options.html}`));
+  if (htmlPath) {
+    console.log(chalk.dim(`HTML report: ${htmlPath}`));
   }
 
   process.exit(failed > 0 || errors > 0 ? 1 : 0);

package/src/index.ts

@@ -6,34 +6,49 @@
  */
 
 import { Command } from 'commander';
+import { createRequire } from 'module';
 import { searchCommand } from './commands/search.js';
 import { infoCommand } from './commands/info.js';
 import { installCommand } from './commands/install.js';
 import { libraryCommand, regenerateCommand } from './commands/library.js';
 import { easyedaSearchCommand, easyedaInstallCommand } from './commands/easyeda.js';
 import { validateCommand } from './commands/validate.js';
+import { getErrorMessage } from './utils/agent-output.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 
 const program = new Command();
 
+function parsePositiveInt(value: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Expected a positive integer, got "${value}"`);
+  }
+  return parsed;
+}
+
 program
   .name('jlc')
   .description('JLC/EasyEDA component sourcing and KiCad library management')
-  .version('0.1.0');
+  .version(version);
 
 program
   .command('search <query...>')
   .description('Search for components (basic parts sorted first)')
-  .option('-l, --limit <number>', 'Maximum results', '20')
+  .option('-l, --limit <number>', 'Maximum results', parsePositiveInt, 20)
   .option('--in-stock', 'Only show in-stock components')
   .option('--basic-only', 'Only show basic parts (no extended)')
   .option('--community', 'Search EasyEDA community library')
+  .option('--json', 'Output clean JSON and do not launch the TUI')
   .action(async (queryParts: string[], options) => {
     const query = queryParts.join(' ');
     await searchCommand(query, {
-      limit: parseInt(options.limit, 10),
+      limit: options.limit,
       inStock: options.inStock,
       basicOnly: options.basicOnly || false,
       source: options.community ? 'easyeda-community' : 'lcsc',
+      json: options.json,
     });
   });
 
@@ -50,11 +65,15 @@ program
   .description('Install component to KiCad libraries')
   .option('-p, --project <path>', 'Install to project-local library')
   .option('--with-3d', 'Include 3D model')
+  .option('-y, --yes', 'Install directly without launching the TUI')
+  .option('--json', 'Output clean JSON and install directly')
   .option('-f, --force', 'Force reinstall (regenerate symbol and footprint)')
   .action(async (id, options) => {
     await installCommand(id, {
       projectPath: options.project,
       include3d: options.with3d,
+      yes: options.yes,
+      json: options.json,
       force: options.force,
     });
   });
@@ -114,11 +133,17 @@ const easyeda = program
 easyeda
   .command('search <query...>')
   .description('Open browser-based component search')
-  .option('-p, --port <number>', 'HTTP server port', '3847')
+  .option('-p, --port <number>', 'HTTP server port', parsePositiveInt, 3847)
+  .option('--json', 'Output clean JSON search results and do not open a browser')
+  .option('--no-open', 'Start the browser server without opening a browser')
+  .option('--once', 'Print the browser URL and exit after the server is ready')
   .action(async (queryParts: string[], options) => {
     const query = queryParts.join(' ');
     await easyedaSearchCommand(query, {
-      port: options.port ? parseInt(options.port, 10) : undefined,
+      port: options.port,
+      json: options.json,
+      open: options.open,
+      once: options.once,
     });
   });
 
@@ -127,13 +152,20 @@ easyeda
   .description('Install EasyEDA community component to KiCad libraries')
   .option('-p, --project <path>', 'Install to project-local library')
   .option('--with-3d', 'Include 3D model')
+  .option('-y, --yes', 'Install directly without launching the TUI')
+  .option('--json', 'Output clean JSON and install directly')
   .option('-f, --force', 'Force reinstall (regenerate symbol and footprint)')
   .action(async (uuid, options) => {
     await easyedaInstallCommand(uuid, {
       projectPath: options.project,
       include3d: options.with3d,
+      yes: options.yes,
+      json: options.json,
       force: options.force,
     });
   });
 
-program.parse();
+program.parseAsync().catch((error) => {
+  console.error(`Error: ${getErrorMessage(error)}`);
+  process.exit(1);
+});

package/src/utils/agent-output.ts

@@ -0,0 +1,35 @@
+export interface JsonError {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+  };
+}
+
+export function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function printJsonError(
+  code: string,
+  message: string,
+  options: { retryable?: boolean; details?: unknown } = {}
+): void {
+  const payload: JsonError = {
+    success: false,
+    error: {
+      code,
+      message,
+      retryable: options.retryable ?? false,
+      details: options.details,
+    },
+  };
+
+  printJson(payload);
+}
+
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/utils/search-result-output.ts

@@ -0,0 +1,20 @@
+import type { ComponentSearchResult } from '@jlcpcb/core';
+
+export function formatSearchResultForJson(result: ComponentSearchResult) {
+  return {
+    id: result.id,
+    id_type: result.idType,
+    lcsc_id: result.idType === 'lcsc' ? result.lcscId : undefined,
+    easyeda_uuid: result.idType === 'easyeda_uuid' ? result.easyedaUuid ?? result.id : undefined,
+    name: result.name,
+    manufacturer: result.manufacturer,
+    description: result.description,
+    package: result.package,
+    datasheet: result.datasheetPdf,
+    stock: result.stock,
+    price: result.price,
+    library_type: result.libraryType,
+    category: result.category,
+    attributes: result.attributes,
+  };
+}