@jlcpcb/core 0.1.0

package/src/types/kicad.ts

@@ -0,0 +1,136 @@
+/**
+ * KiCad-specific types for schematic and PCB manipulation
+ */
+
+export interface PinDefinition {
+  number: string;
+  name: string;
+  electricalType: 'input' | 'output' | 'bidirectional' | 'power_in' | 'power_out' | 'passive' | 'unspecified' | 'open_collector' | 'open_emitter' | 'no_connect';
+  x: number;
+  y: number;
+  rotation: number;
+  length: number;
+}
+
+export interface PadDefinition {
+  number: string;
+  type: 'thru_hole' | 'smd' | 'connect' | 'np_thru_hole';
+  shape: 'circle' | 'rect' | 'oval' | 'trapezoid' | 'roundrect' | 'custom';
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  drill?: number;
+  layers: string[];
+}
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface KiCadSymbol {
+  name: string;
+  library: string;
+  pins: PinDefinition[];
+  properties: Record<string, string>;
+}
+
+export interface KiCadFootprint {
+  name: string;
+  library: string;
+  pads: PadDefinition[];
+  layers: string[];
+  courtyard: BoundingBox;
+  properties: Record<string, string>;
+}
+
+export interface SchematicComponent {
+  reference: string;
+  value: string;
+  symbol: string;
+  footprint: string;
+  position: { x: number; y: number };
+  rotation: number;
+  properties: Record<string, string>;
+}
+
+export interface Wire {
+  startX: number;
+  startY: number;
+  endX: number;
+  endY: number;
+}
+
+export interface NetLabel {
+  name: string;
+  x: number;
+  y: number;
+  rotation: number;
+}
+
+export interface SchematicSheet {
+  name: string;
+  filename: string;
+  position: { x: number; y: number };
+}
+
+export interface KiCadSchematic {
+  version: string;
+  components: SchematicComponent[];
+  wires: Wire[];
+  labels: NetLabel[];
+  sheets: SchematicSheet[];
+}
+
+export interface KiCadPCB {
+  version: string;
+  layers: PCBLayer[];
+  components: PCBComponent[];
+  traces: Trace[];
+  vias: Via[];
+  zones: Zone[];
+  boardOutline: BoardOutline;
+}
+
+export interface PCBLayer {
+  number: number;
+  name: string;
+  type: 'signal' | 'power' | 'mixed' | 'user';
+}
+
+export interface PCBComponent {
+  reference: string;
+  footprint: string;
+  position: { x: number; y: number };
+  rotation: number;
+  layer: 'F.Cu' | 'B.Cu';
+}
+
+export interface Trace {
+  net: string;
+  width: number;
+  layer: string;
+  points: { x: number; y: number }[];
+}
+
+export interface Via {
+  net: string;
+  position: { x: number; y: number };
+  size: number;
+  drill: number;
+  layers: [string, string];
+}
+
+export interface Zone {
+  net: string;
+  layer: string;
+  priority: number;
+  outline: { x: number; y: number }[];
+}
+
+export interface BoardOutline {
+  points: { x: number; y: number }[];
+}

package/src/types/mcp.ts

@@ -0,0 +1,77 @@
+/**
+ * MCP protocol types for AI-EDA tools
+ */
+
+export interface MCPToolResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+export interface MCPContent {
+  type: 'text' | 'image' | 'resource';
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}
+
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, MCPPropertySchema>;
+    required?: string[];
+  };
+}
+
+export interface MCPPropertySchema {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: string[];
+  items?: MCPPropertySchema;
+  default?: unknown;
+}
+
+export interface MCPServerInfo {
+  name: string;
+  version: string;
+  capabilities: {
+    tools?: boolean;
+    resources?: boolean;
+    prompts?: boolean;
+  };
+}
+
+// Tool-specific types
+export interface ComponentSearchParams {
+  query: string;
+  category?: string;
+  inStock?: boolean;
+  limit?: number;
+}
+
+export interface LibraryFetchParams {
+  lcscPartNumber: string;
+  outputDir?: string;
+  include3D?: boolean;
+}
+
+export interface DatasheetDownloadParams {
+  lcscPartNumber: string;
+  outputPath?: string;
+}
+
+export interface SchematicParams {
+  projectPath: string;
+  sheetName?: string;
+}
+
+export interface PCBParams {
+  projectPath: string;
+}
+
+export interface ExportParams {
+  projectPath: string;
+  format: 'jlcpcb' | 'pcbway' | 'oshpark' | 'generic';
+  outputDir?: string;
+}

package/src/types/project.ts

@@ -0,0 +1,60 @@
+/**
+ * Project structure and configuration types
+ */
+
+import type { ComponentSelection } from './component.js';
+
+export interface EDAProject {
+  name: string;
+  version: string;
+  created: string;
+  modified: string;
+  constraints: DesignConstraints;
+  components: ComponentSelection[];
+  status: ProjectStatus;
+}
+
+export interface DesignConstraints {
+  boardSize?: { width: number; height: number; unit: 'mm' | 'inch' };
+  layers: number;
+  powerSource: PowerSourceSpec;
+  interfaces: InterfaceSpec[];
+  environment?: EnvironmentSpec;
+  manufacturingClass?: number;  // IPC class 1/2/3
+}
+
+export interface PowerSourceSpec {
+  type: 'usb' | 'battery' | 'dc_jack' | 'poe' | 'other';
+  voltage: { min: number; max: number };
+  current?: number;
+  details?: string;
+}
+
+export interface InterfaceSpec {
+  type: 'usb' | 'uart' | 'spi' | 'i2c' | 'ethernet' | 'wifi' | 'bluetooth' | 'can' | 'rs485' | 'gpio' | 'adc' | 'dac' | 'pwm' | 'other';
+  count?: number;
+  details?: string;
+}
+
+export interface EnvironmentSpec {
+  tempMin: number;
+  tempMax: number;
+  indoor: boolean;
+  certifications?: string[];
+}
+
+export interface ProjectStatus {
+  phase: 'specification' | 'component_selection' | 'schematic' | 'pcb_layout' | 'validation' | 'manufacturing';
+  schematicComplete: boolean;
+  pcbComplete: boolean;
+  validated: boolean;
+  exported: boolean;
+}
+
+export interface ProjectConfig {
+  kicadProjectDir: string;
+  librariesDir: string;
+  datasheetsDir: string;
+  productionDir: string;
+  docsDir: string;
+}

package/src/utils/conversion.ts

@@ -0,0 +1,104 @@
+/**
+ * Unit conversion utilities for EDA operations
+ */
+
+// EasyEDA uses 10mil units (0.254mm per unit)
+export const EASYEDA_TO_MM = 0.254;
+export const MM_TO_EASYEDA = 1 / EASYEDA_TO_MM;
+
+// KiCad uses mm as default
+export const MM_TO_MIL = 39.3701;
+export const MIL_TO_MM = 0.0254;
+export const MM_TO_INCH = 0.0393701;
+export const INCH_TO_MM = 25.4;
+
+/**
+ * Convert EasyEDA units to millimeters
+ */
+export function easyedaToMm(value: number): number {
+  return value * EASYEDA_TO_MM;
+}
+
+/**
+ * Convert millimeters to EasyEDA units
+ */
+export function mmToEasyeda(value: number): number {
+  return value * MM_TO_EASYEDA;
+}
+
+/**
+ * Convert mils to millimeters
+ */
+export function milToMm(value: number): number {
+  return value * MIL_TO_MM;
+}
+
+/**
+ * Convert millimeters to mils
+ */
+export function mmToMil(value: number): number {
+  return value * MM_TO_MIL;
+}
+
+/**
+ * Convert inches to millimeters
+ */
+export function inchToMm(value: number): number {
+  return value * INCH_TO_MM;
+}
+
+/**
+ * Convert millimeters to inches
+ */
+export function mmToInch(value: number): number {
+  return value * MM_TO_INCH;
+}
+
+/**
+ * Round to a specific number of decimal places
+ */
+export function roundTo(value: number, decimals: number = 4): number {
+  const multiplier = Math.pow(10, decimals);
+  return Math.round(value * multiplier) / multiplier;
+}
+
+/**
+ * Convert angle from degrees to radians
+ */
+export function degToRad(degrees: number): number {
+  return (degrees * Math.PI) / 180;
+}
+
+/**
+ * Convert angle from radians to degrees
+ */
+export function radToDeg(radians: number): number {
+  return (radians * 180) / Math.PI;
+}
+
+/**
+ * Normalize angle to 0-360 range
+ */
+export function normalizeAngle(angle: number): number {
+  return ((angle % 360) + 360) % 360;
+}
+
+/**
+ * Calculate trace width for given current and temperature rise
+ * Using IPC-2221 standard for external layers
+ * @param currentAmps - Current in amperes
+ * @param tempRiseC - Temperature rise in Celsius (default 10)
+ * @param copperOz - Copper weight in oz/ft² (default 1)
+ * @returns Trace width in mm
+ */
+export function calculateTraceWidth(
+  currentAmps: number,
+  tempRiseC: number = 10,
+  copperOz: number = 1
+): number {
+  // IPC-2221 formula for external layers
+  const area = Math.pow(currentAmps / (0.048 * Math.pow(tempRiseC, 0.44)), 1 / 0.725);
+  const thickness = copperOz * 0.035; // mm
+  const width = area / (thickness * 1000); // convert from mils² to mm
+  return roundTo(width, 3);
+}

package/src/utils/file-system.ts

@@ -0,0 +1,143 @@
+/**
+ * File system operation helpers
+ */
+
+import { readdir, readFile, writeFile, mkdir, access, stat } from 'fs/promises';
+import { join, dirname, extname, basename } from 'path';
+
+/**
+ * Check if a path exists
+ */
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path is a directory
+ */
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path is a file
+ */
+export async function isFile(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export async function ensureDir(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+}
+
+/**
+ * Ensure the parent directory of a file exists
+ */
+export async function ensureParentDir(filePath: string): Promise<void> {
+  const parentDir = dirname(filePath);
+  await ensureDir(parentDir);
+}
+
+/**
+ * Read a JSON file and parse it
+ */
+export async function readJson<T = unknown>(path: string): Promise<T> {
+  const content = await readFile(path, 'utf-8');
+  return JSON.parse(content) as T;
+}
+
+/**
+ * Write an object to a JSON file
+ */
+export async function writeJson(path: string, data: unknown, pretty: boolean = true): Promise<void> {
+  await ensureParentDir(path);
+  const content = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+  await writeFile(path, content, 'utf-8');
+}
+
+/**
+ * Read a text file
+ */
+export async function readText(path: string): Promise<string> {
+  return readFile(path, 'utf-8');
+}
+
+/**
+ * Write text to a file
+ */
+export async function writeText(path: string, content: string): Promise<void> {
+  await ensureParentDir(path);
+  await writeFile(path, content, 'utf-8');
+}
+
+/**
+ * Write binary data to a file
+ */
+export async function writeBinary(path: string, data: Buffer | Uint8Array): Promise<void> {
+  await ensureParentDir(path);
+  await writeFile(path, data);
+}
+
+/**
+ * List files in a directory with optional filtering
+ */
+export async function listFiles(
+  dir: string,
+  options: { extensions?: string[]; recursive?: boolean } = {}
+): Promise<string[]> {
+  const { extensions, recursive = false } = options;
+  const files: string[] = [];
+
+  async function scanDir(currentDir: string): Promise<void> {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isDirectory() && recursive) {
+        await scanDir(fullPath);
+      } else if (entry.isFile()) {
+        if (!extensions || extensions.includes(extname(entry.name))) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+
+  await scanDir(dir);
+  return files;
+}
+
+/**
+ * Get the filename without extension
+ */
+export function getBaseName(filePath: string): string {
+  return basename(filePath, extname(filePath));
+}
+
+/**
+ * Copy a file
+ */
+export async function copyFile(src: string, dest: string): Promise<void> {
+  await ensureParentDir(dest);
+  const content = await readFile(src);
+  await writeFile(dest, content);
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * ai-eda-common utilities
+ */
+
+export * from './conversion.js';
+export * from './validation.js';
+export * from './file-system.js';
+export * from './logger.js';

package/src/utils/logger.ts

@@ -0,0 +1,96 @@
+/**
+ * Consistent logging utility for AI-EDA packages
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LoggerOptions {
+  level: LogLevel;
+  prefix?: string;
+  timestamps?: boolean;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+export class Logger {
+  private level: LogLevel;
+  private prefix: string;
+  private timestamps: boolean;
+
+  constructor(options: Partial<LoggerOptions> = {}) {
+    this.level = options.level ?? 'info';
+    this.prefix = options.prefix ?? '';
+    this.timestamps = options.timestamps ?? false;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+
+  private formatMessage(level: LogLevel, message: string): string {
+    const parts: string[] = [];
+
+    if (this.timestamps) {
+      parts.push(`[${new Date().toISOString()}]`);
+    }
+
+    parts.push(`[${level.toUpperCase()}]`);
+
+    if (this.prefix) {
+      parts.push(`[${this.prefix}]`);
+    }
+
+    parts.push(message);
+
+    return parts.join(' ');
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('debug')) {
+      console.error(this.formatMessage('debug', message), ...args);
+    }
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('info')) {
+      console.error(this.formatMessage('info', message), ...args);
+    }
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('warn')) {
+      console.error(this.formatMessage('warn', message), ...args);
+    }
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('error')) {
+      console.error(this.formatMessage('error', message), ...args);
+    }
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  child(prefix: string): Logger {
+    return new Logger({
+      level: this.level,
+      prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+      timestamps: this.timestamps,
+    });
+  }
+}
+
+// Default logger instance
+export const logger = new Logger({ prefix: 'ai-eda' });
+
+// Create package-specific loggers
+export function createLogger(packageName: string): Logger {
+  return logger.child(packageName);
+}