@jlcpcb/cli 0.3.1 → 0.4.0

package/src/commands/search.ts

@@ -5,11 +5,19 @@
 
 import { createComponentService, 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();
 
-export async function searchCommand(query: string, options: SearchOptions): Promise<void> {
-  console.log(`Searching for "${query}"...`);
+interface SearchCommandOptions extends SearchOptions {
+  json?: boolean;
+}
+
+export async function searchCommand(query: string, options: SearchCommandOptions): Promise<void> {
+  if (!options.json) {
+    console.log(`Searching for "${query}"...`);
+  }
 
   try {
     let results = await componentService.search(query, options);
@@ -24,15 +32,39 @@ export async function searchCommand(query: string, options: SearchOptions): Prom
     }
 
     if (results.length === 0) {
+      if (options.json) {
+        printJson({
+          success: true,
+          query,
+          count: 0,
+          results: [],
+        });
+        return;
+      }
+
       console.log('No components found. Try a different search term.');
       return;
     }
 
+    if (options.json) {
+      printJson({
+        success: true,
+        query,
+        count: results.length,
+        results: results.map(formatSearchResultForJson),
+      });
+      return;
+    }
+
     // Clear the "Searching..." line and launch interactive UI
     process.stdout.write('\x1b[1A\x1b[2K');
     await renderApp('search', { query, results });
   } catch (error) {
-    console.error(`Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    if (options.json) {
+      printJsonError('search_failed', getErrorMessage(error), { retryable: true });
+    } else {
+      console.error(`Search failed: ${getErrorMessage(error)}`);
+    }
     process.exit(1);
   }
 }

package/src/commands/validate.ts

@@ -30,6 +30,7 @@ import {
   footprintConverter,
   symbolConverter,
 } from '@jlcpcb/core';
+import { printJson, printJsonError } from '../utils/agent-output.js';
 
 interface ValidateOptions {
   footprintOnly?: boolean;
@@ -130,46 +131,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);
-    }
+    spinner?.stop(result.passed ? chalk.green('✓ Validation passed') : chalk.red('✗ Validation failed'));
 
-    if (result.footprint) {
-      console.log(formatComparisonResult(result.footprint));
-    }
+    let htmlPath: string | undefined;
 
-    if (result.symbol) {
-      console.log(formatSymbolComparisonResult(result.symbol));
-    }
-
-    // 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 +182,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 +229,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 +257,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,7 +280,9 @@ 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,
@@ -255,32 +293,46 @@ export async function validateCommand(
 
     if (result.error) {
       errors++;
-      console.log(chalk.yellow('⚠ ERROR'));
+      if (!options.json) console.log(chalk.yellow('⚠ 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/package-metadata.test.ts

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+
+import { describe, expect, it } from "bun:test";
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+};
+
+async function readPackageJson(): Promise<PackageJson> {
+  const packageJsonPath = new URL("../package.json", import.meta.url);
+  const packageJson = await readFile(packageJsonPath, "utf8");
+  return JSON.parse(packageJson) as PackageJson;
+}
+
+describe("package metadata", () => {
+  it("does not publish workspace protocol runtime dependencies", async () => {
+    const packageJson = await readPackageJson();
+    const workspaceDependencies = Object.entries(packageJson.dependencies ?? {})
+      .filter(([, version]) => version.startsWith("workspace:"))
+      .map(([name]) => name);
+
+    expect(workspaceDependencies).toEqual([]);
+    expect(packageJson.dependencies?.["@jlcpcb/core"]).toBeUndefined();
+  });
+});

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,
+  };
+}