@jlcpcb/cli 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jlcpcb/cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "CLI for JLC/EasyEDA component sourcing and KiCad library management",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/l3wi/jlc-cli.git",
+    "directory": "packages/jlc-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "jlc": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node",
+    "dev": "bun --watch ./src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "jlcpcb",
+    "jlc",
+    "easyeda",
+    "kicad",
+    "electronics",
+    "components",
+    "pcb",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ink": "6.6.0",
+    "ink-select-input": "6.2.0",
+    "@jlcpcb/core": "workspace:*",
+    "open": "11.0.0",
+    "react-devtools-core": "7.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "19.2.7"
+  }
+}

package/src/app/App.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import { render, Box, useInput, useApp } from 'ink';
+import { NavigationProvider, useNavigation, useCurrentScreen } from './navigation/NavigationContext.js';
+import { AppStateProvider } from './state/AppStateContext.js';
+import { SearchScreen } from './screens/SearchScreen.js';
+import { InfoScreen } from './screens/InfoScreen.js';
+import { InstallScreen } from './screens/InstallScreen.js';
+import { InstalledScreen } from './screens/InstalledScreen.js';
+import { LibraryScreen } from './screens/LibraryScreen.js';
+import { LibrarySetupScreen } from './screens/LibrarySetupScreen.js';
+import type { ScreenName, ScreenParams } from './navigation/types.js';
+
+function ScreenRouter() {
+  const { screen } = useCurrentScreen();
+
+  switch (screen) {
+    case 'search':
+      return <SearchScreen />;
+    case 'info':
+      return <InfoScreen />;
+    case 'install':
+      return <InstallScreen />;
+    case 'installed':
+      return <InstalledScreen />;
+    case 'library':
+      return <LibraryScreen />;
+    case 'library-setup':
+      return <LibrarySetupScreen />;
+    default:
+      return null;
+  }
+}
+
+function AppContent() {
+  const { exit } = useApp();
+  const { pop, currentIndex, history } = useNavigation();
+  const { screen } = useCurrentScreen();
+
+  useInput((input, key) => {
+    // Global ESC handler - pops navigation or exits at root
+    // Note: Individual screens handle their own keys, this is just for ESC
+    if (key.escape) {
+      // Don't allow ESC during install (it auto-navigates when done)
+      if (screen === 'install') return;
+
+      const didPop = pop();
+      if (!didPop) {
+        exit();
+      }
+    }
+
+    // 'q' to quit from root screen
+    if (input === 'q' && currentIndex === 0) {
+      exit();
+    }
+  });
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <ScreenRouter />
+    </Box>
+  );
+}
+
+interface AppProps<T extends ScreenName> {
+  initialScreen: T;
+  initialParams: ScreenParams[T];
+}
+
+export function App<T extends ScreenName>({ initialScreen, initialParams }: AppProps<T>) {
+  return (
+    <NavigationProvider initialScreen={initialScreen} initialParams={initialParams}>
+      <AppStateProvider>
+        <AppContent />
+      </AppStateProvider>
+    </NavigationProvider>
+  );
+}
+
+export function renderApp<T extends ScreenName>(
+  initialScreen: T,
+  initialParams: ScreenParams[T]
+): void {
+  render(<App initialScreen={initialScreen} initialParams={initialParams} />);
+}

package/src/app/components/DetailView.tsx

@@ -0,0 +1,173 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { InstalledComponent } from '@jlcpcb/core';
+import { Divider } from './Divider.js';
+
+// Flexible component type that accepts both ComponentSearchResult and ComponentDetails
+export interface DetailViewComponent {
+  lcscId: string;
+  name?: string;
+  manufacturer?: string;
+  package?: string;
+  stock?: number;
+  price?: number;
+  libraryType?: 'basic' | 'extended';
+  description?: string;
+  datasheetPdf?: string;
+  datasheet?: string; // ComponentDetails uses this instead of datasheetPdf
+  attributes?: Record<string, unknown>;
+}
+
+interface DetailViewProps {
+  component: DetailViewComponent;
+  terminalWidth: number;
+  isInstalled?: boolean;
+  installedInfo?: InstalledComponent | null;
+  statusMessage?: string | null;
+}
+
+function formatStock(stock: number): string {
+  if (stock < 1000) return String(stock);
+  return '>1k';
+}
+
+function truncate(str: string, len: number): string {
+  if (!str) return '';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}
+
+export function DetailView({ component, terminalWidth, isInstalled, installedInfo, statusMessage }: DetailViewProps) {
+  const isWide = terminalWidth >= 80;
+  const labelWidth = 16;
+  // In wide mode, split into two columns with gap; otherwise full width
+  const colWidth = isWide ? Math.floor((terminalWidth - 4) / 2) : terminalWidth - 2;
+  const valueWidth = colWidth - labelWidth - 1;
+  const attrLabelWidth = 20;
+  const attrValueWidth = colWidth - attrLabelWidth - 1;
+
+  const description = (
+    <Box flexDirection="column" marginBottom={1} width={terminalWidth - 2}>
+      <Text dimColor>Description</Text>
+      <Text wrap="wrap">{component.description || 'No description'}</Text>
+    </Box>
+  );
+
+  const partInfo = (
+    <Box flexDirection="column" width={colWidth}>
+      <Text bold underline color="cyan">Part Info</Text>
+      <Box marginTop={1} flexDirection="column">
+        <Box>
+          <Text dimColor>{'Manufacturer'.padEnd(labelWidth)}</Text>
+          <Text>{truncate(component.manufacturer || 'N/A', valueWidth)}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'MFR.Part #'.padEnd(labelWidth)}</Text>
+          <Text bold>{truncate(component.name || 'N/A', valueWidth)}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'JLCPCB Part #'.padEnd(labelWidth)}</Text>
+          <Text color="cyan" bold>{component.lcscId}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Package'.padEnd(labelWidth)}</Text>
+          <Text>{truncate(component.package || 'N/A', valueWidth)}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Stock'.padEnd(labelWidth)}</Text>
+          <Text>{component.stock !== undefined ? formatStock(component.stock) : 'N/A'}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Price'.padEnd(labelWidth)}</Text>
+          <Text color="green">{component.price ? `$${component.price.toFixed(4)}` : 'N/A'}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Library Type'.padEnd(labelWidth)}</Text>
+          <Text color={component.libraryType === 'basic' ? 'green' : 'yellow'}>
+            {component.libraryType === 'basic' ? 'Basic' : 'Extended'}
+          </Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+
+  const hasAttributes = component.attributes && Object.keys(component.attributes).length > 0;
+  const attributes = hasAttributes ? (
+    <Box flexDirection="column" marginLeft={isWide ? 2 : 0} marginTop={isWide ? 0 : 1} width={colWidth}>
+      <Text bold underline color="cyan">Attributes</Text>
+      <Box marginTop={1} flexDirection="column">
+        {Object.entries(component.attributes!).slice(0, 10).map(([key, value]) => {
+          const keyWidth = Math.max(key.length + 1, attrLabelWidth);
+          const remainingWidth = colWidth - keyWidth - 1;
+          return (
+            <Box key={key}>
+              <Text dimColor>{key.padEnd(keyWidth)}</Text>
+              <Text>{truncate(String(value), remainingWidth)}</Text>
+            </Box>
+          );
+        })}
+      </Box>
+    </Box>
+  ) : null;
+
+  const datasheetUrl = component.datasheetPdf || component.datasheet;
+  const datasheet = datasheetUrl ? (
+    <Box flexDirection="column" marginTop={1} width={terminalWidth - 2}>
+      <Text dimColor>Datasheet</Text>
+      <Text color="blue" wrap="wrap">{truncate(datasheetUrl, terminalWidth - 4)}</Text>
+    </Box>
+  ) : null;
+
+  // Show installation info if installed
+  const installInfo = isInstalled && installedInfo ? (
+    <Box flexDirection="column" marginTop={1} width={terminalWidth - 2}>
+      <Text bold underline color="green">Installation</Text>
+      <Box marginTop={1} flexDirection="column">
+        <Box>
+          <Text dimColor>{'Symbol'.padEnd(labelWidth)}</Text>
+          <Text color="cyan">{truncate(installedInfo.symbolRef, terminalWidth - labelWidth - 4)}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Footprint'.padEnd(labelWidth)}</Text>
+          <Text color="cyan">{truncate(installedInfo.footprintRef || 'N/A', terminalWidth - labelWidth - 4)}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'3D Model'.padEnd(labelWidth)}</Text>
+          <Text color={installedInfo.has3dModel ? 'green' : 'yellow'}>
+            {installedInfo.has3dModel ? 'Yes' : 'No'}
+          </Text>
+        </Box>
+      </Box>
+    </Box>
+  ) : null;
+
+  // Footer text based on installation status
+  const footerText = isInstalled
+    ? 'S Symbol • F Footprint • M 3D Model • R Regenerate • D Datasheet • Esc Back'
+    : 'Enter Install • D Datasheet • Esc Back';
+
+  return (
+    <Box flexDirection="column" width="100%">
+      {description}
+      <Box flexDirection={isWide ? 'row' : 'column'} width="100%">
+        {partInfo}
+        {attributes}
+      </Box>
+      {installInfo}
+      {datasheet}
+      <Box marginTop={1} flexDirection="column" width="100%">
+        <Divider width={terminalWidth} />
+        {statusMessage && (
+          <Box paddingY={0}>
+            <Text color={statusMessage.startsWith('✓') ? 'green' : statusMessage.startsWith('✗') ? 'red' : 'yellow'}>
+              {statusMessage}
+            </Text>
+          </Box>
+        )}
+        <Box paddingY={0}>
+          <Text dimColor>{footerText}</Text>
+        </Box>
+        <Divider width={terminalWidth} />
+      </Box>
+    </Box>
+  );
+}

package/src/app/components/Divider.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { Text } from 'ink';
+
+interface DividerProps {
+  width: number;
+}
+
+export function Divider({ width }: DividerProps) {
+  return <Text dimColor>{'─'.repeat(Math.max(width - 2, 10))}</Text>;
+}

package/src/app/components/InstalledView.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import { Divider } from './Divider.js';
+
+// Minimal component type for installed view
+export interface InstalledViewComponent {
+  lcscId: string;
+  name?: string;
+}
+
+interface InstalledViewProps {
+  component: InstalledViewComponent;
+  result: { symbolRef: string; footprintRef: string } | null;
+  error: string | null;
+  terminalWidth: number;
+}
+
+export function InstalledView({
+  component,
+  result,
+  error,
+  terminalWidth,
+}: InstalledViewProps) {
+  if (error) {
+    return (
+      <Box flexDirection="column">
+        <Text color="red">✗ Installation failed: {error}</Text>
+        <Box marginTop={1} flexDirection="column">
+          <Divider width={terminalWidth} />
+          <Text dimColor>Press any key to go back</Text>
+          <Divider width={terminalWidth} />
+        </Box>
+      </Box>
+    );
+  }
+
+  if (!result) {
+    return (
+      <Box flexDirection="column">
+        <Text color="red">✗ Installation failed</Text>
+        <Box marginTop={1} flexDirection="column">
+          <Divider width={terminalWidth} />
+          <Text dimColor>Press any key to go back</Text>
+          <Divider width={terminalWidth} />
+        </Box>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column">
+      <Text color="green" bold>✓ Installed {component.lcscId}</Text>
+      <Box marginTop={1} flexDirection="column">
+        <Box>
+          <Text dimColor>{'Symbol     '}</Text>
+          <Text color="cyan">{result.symbolRef}</Text>
+        </Box>
+        <Box>
+          <Text dimColor>{'Footprint  '}</Text>
+          <Text color="cyan">{result.footprintRef}</Text>
+        </Box>
+      </Box>
+      <Box marginTop={1} flexDirection="column">
+        <Divider width={terminalWidth} />
+        <Text dimColor>Press any key to continue</Text>
+        <Divider width={terminalWidth} />
+      </Box>
+    </Box>
+  );
+}

package/src/app/components/ListView.tsx

@@ -0,0 +1,93 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { ComponentSearchResult } from '@jlcpcb/core';
+import { Divider } from './Divider.js';
+
+interface ListViewProps {
+  results: ComponentSearchResult[];
+  selectedIndex: number;
+  isFiltered: boolean;
+  terminalWidth: number;
+}
+
+function formatStock(stock: number): string {
+  if (stock < 1000) return String(stock);
+  return '>1k';
+}
+
+function truncate(str: string, len: number): string {
+  if (!str) return '';
+  return str.length > len ? str.slice(0, len - 1) + '…' : str;
+}
+
+export function ListView({
+  results,
+  selectedIndex,
+  isFiltered,
+  terminalWidth,
+}: ListViewProps) {
+  // Calculate column widths based on terminal width
+  const minWidth = 80;
+  const availableWidth = Math.max(terminalWidth - 4, minWidth);
+
+  // Fixed columns: MFR.Part(18), Package(10), Stock(6), Price(8), Library(10) + spacing
+  const mfrPartWidth = 18;
+  const pkgWidth = 10;
+  const stockWidth = 6;
+  const priceWidth = 8;
+  const libraryWidth = 10;
+  const fixedWidth = mfrPartWidth + pkgWidth + stockWidth + priceWidth + libraryWidth + 4; // +4 for spacing
+
+  // Description gets all remaining space
+  const descWidth = Math.max(availableWidth - fixedWidth, 15);
+
+  return (
+    <Box flexDirection="column">
+      <Box marginBottom={1}>
+        <Text bold dimColor>
+          {'  '}
+          {'MFR.Part'.padEnd(mfrPartWidth)}
+          {'Description'.padEnd(descWidth)}
+          {'Package'.padEnd(pkgWidth)}
+          {'Stock'.padStart(stockWidth)}
+          {'Price'.padStart(priceWidth)}
+          {'  Library'}
+        </Text>
+      </Box>
+      {results.map((r, i) => {
+        const isSelected = i === selectedIndex;
+        const mfrPart = truncate(r.name || '', mfrPartWidth - 1).padEnd(mfrPartWidth);
+        const desc = truncate(r.description || '', descWidth - 1).padEnd(descWidth);
+        const pkg = truncate(r.package || '', pkgWidth - 1).padEnd(pkgWidth);
+        const stock = formatStock(r.stock || 0).padStart(stockWidth);
+        const price = r.price ? `$${r.price.toFixed(2)}`.padStart(priceWidth) : '     N/A';
+        const library = r.libraryType === 'basic' ? 'Basic' : 'Extended';
+        const libraryColor = r.libraryType === 'basic' ? 'green' : 'yellow';
+
+        return (
+          <Box key={r.lcscId}>
+            <Text color="cyan">{isSelected ? '▶' : '  '}</Text>
+            <Text inverse={isSelected}>
+              <Text color="cyan">{mfrPart}</Text>
+              <Text dimColor>{desc}</Text>
+              {pkg}
+              {stock}
+              {price}
+              {'  '}
+              <Text color={libraryColor}>{library}</Text>
+            </Text>
+          </Box>
+        );
+      })}
+      <Box marginTop={1} flexDirection="column">
+        <Divider width={terminalWidth} />
+        <Box paddingY={0}>
+          <Text dimColor>
+            ↑/↓ Navigate • Enter View • Tab {isFiltered ? 'All Parts' : 'Basic Only'} • Esc Back
+          </Text>
+        </Box>
+        <Divider width={terminalWidth} />
+      </Box>
+    </Box>
+  );
+}

package/src/app/hooks/useTerminalSize.ts

@@ -0,0 +1,29 @@
+import { useState, useEffect } from 'react';
+
+export interface TerminalSize {
+  columns: number;
+  rows: number;
+}
+
+export function useTerminalSize(): TerminalSize {
+  const [size, setSize] = useState<TerminalSize>({
+    columns: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  });
+
+  useEffect(() => {
+    const handleResize = () => {
+      setSize({
+        columns: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+      });
+    };
+
+    process.stdout.on('resize', handleResize);
+    return () => {
+      process.stdout.off('resize', handleResize);
+    };
+  }, []);
+
+  return size;
+}

package/src/app/navigation/NavigationContext.tsx

@@ -0,0 +1,87 @@
+import React, { createContext, useContext, useState, useCallback, type ReactNode } from 'react';
+import type {
+  NavigationContextValue,
+  ScreenName,
+  ScreenParams,
+  HistoryEntry,
+} from './types.js';
+
+const NavigationContext = createContext<NavigationContextValue | null>(null);
+
+interface NavigationProviderProps<T extends ScreenName> {
+  initialScreen: T;
+  initialParams: ScreenParams[T];
+  children: ReactNode;
+}
+
+export function NavigationProvider<T extends ScreenName>({
+  initialScreen,
+  initialParams,
+  children,
+}: NavigationProviderProps<T>) {
+  const [history, setHistory] = useState<HistoryEntry[]>([
+    { screen: initialScreen, params: initialParams },
+  ]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  const push = useCallback(
+    <S extends ScreenName>(screen: S, params: ScreenParams[S]) => {
+      setHistory((prev) => [
+        ...prev.slice(0, currentIndex + 1),
+        { screen, params } as HistoryEntry,
+      ]);
+      setCurrentIndex((prev) => prev + 1);
+    },
+    [currentIndex]
+  );
+
+  const pop = useCallback(() => {
+    if (currentIndex > 0) {
+      setCurrentIndex((prev) => prev - 1);
+      return true;
+    }
+    return false;
+  }, [currentIndex]);
+
+  const replace = useCallback(
+    <S extends ScreenName>(screen: S, params: ScreenParams[S]) => {
+      setHistory((prev) => {
+        const newHistory = [...prev];
+        newHistory[currentIndex] = { screen, params } as HistoryEntry;
+        return newHistory;
+      });
+    },
+    [currentIndex]
+  );
+
+  const reset = useCallback(<S extends ScreenName>(screen: S, params: ScreenParams[S]) => {
+    setHistory([{ screen, params } as HistoryEntry]);
+    setCurrentIndex(0);
+  }, []);
+
+  const value: NavigationContextValue = {
+    history,
+    currentIndex,
+    push,
+    pop,
+    replace,
+    reset,
+  };
+
+  return (
+    <NavigationContext.Provider value={value}>{children}</NavigationContext.Provider>
+  );
+}
+
+export function useNavigation(): NavigationContextValue {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    throw new Error('useNavigation must be used within NavigationProvider');
+  }
+  return context;
+}
+
+export function useCurrentScreen(): HistoryEntry {
+  const { history, currentIndex } = useNavigation();
+  return history[currentIndex];
+}

package/src/app/navigation/types.ts

@@ -0,0 +1,66 @@
+import type { ComponentSearchResult, ComponentDetails, InstallResult, InstalledComponent, LibraryStatus } from '@jlcpcb/core';
+
+export type ScreenName = 'search' | 'info' | 'install' | 'library' | 'library-setup' | 'installed';
+
+// Common component type that works across screens
+export type ComponentInfo = ComponentSearchResult | ComponentDetails;
+
+export interface SearchParams {
+  query: string;
+  results: ComponentSearchResult[];
+}
+
+export interface InfoParams {
+  componentId: string;
+  component?: ComponentInfo;
+}
+
+export interface InstallParams {
+  componentId: string;
+  component: ComponentInfo;
+}
+
+export interface LibraryParams {
+  status?: LibraryStatus;
+  installed?: InstalledComponent[];
+}
+
+export interface LibrarySetupParams {
+  componentId: string;
+  component: ComponentInfo;
+}
+
+export interface InstalledParams {
+  componentId: string;
+  component: ComponentInfo;
+  result?: InstallResult;
+  error?: string;
+}
+
+export interface ScreenParams {
+  search: SearchParams;
+  info: InfoParams;
+  install: InstallParams;
+  library: LibraryParams;
+  'library-setup': LibrarySetupParams;
+  installed: InstalledParams;
+}
+
+export interface HistoryEntry<T extends ScreenName = ScreenName> {
+  screen: T;
+  params: ScreenParams[T];
+}
+
+export interface NavigationState {
+  history: HistoryEntry[];
+  currentIndex: number;
+}
+
+export interface NavigationActions {
+  push: <T extends ScreenName>(screen: T, params: ScreenParams[T]) => void;
+  pop: () => boolean;
+  replace: <T extends ScreenName>(screen: T, params: ScreenParams[T]) => void;
+  reset: <T extends ScreenName>(screen: T, params: ScreenParams[T]) => void;
+}
+
+export type NavigationContextValue = NavigationState & NavigationActions;