@jlcpcb/cli 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jlcpcb/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "description": "CLI for JLC/EasyEDA component sourcing and KiCad library management",

package/src/app/App.tsx

@@ -36,7 +36,7 @@ function ScreenRouter() {
 
 function AppContent() {
   const { exit } = useApp();
-  const { pop, currentIndex, history } = useNavigation();
+  const { pop, currentIndex } = useNavigation();
   const { screen } = useCurrentScreen();
 
   useInput((input, key) => {

package/src/app/__fixtures__/interactive-install-scenarios.tsx

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mock, spyOn } from 'bun:test';
+import React from 'react';
+import {
+  createLibraryService, getLibraryPaths, easyedaClient, easyedaCommunityClient, jlcClient,
+  type EasyEDAComponentData, type EasyEDACommunityComponent,
+} from '@jlcpcb/core';
+import type { ScreenName, ScreenParams } from '../navigation/types.js';
+import { createTerminal } from './terminal.js';
+
+const scenario = process.argv[2];
+const root = process.argv[3];
+const projectPath = join(root, 'selected-project');
+await mkdir(projectPath, { recursive: true });
+// Any forgotten upstream dependency must fail rather than reaching the network.
+spyOn(globalThis, 'fetch').mockRejectedValue(new Error('Unexpected network request in interactive install fixture'));
+const component: EasyEDAComponentData = {
+  info: { name: 'Interactive Part', prefix: 'U', lcscId: 'C400', package: 'Custom_Interactive_Package' },
+  symbol: {
+    pins: [], rectangles: [], circles: [], ellipses: [], arcs: [], polylines: [],
+    polygons: [], paths: [], texts: [], origin: { x: 0, y: 0 },
+  },
+  footprint: {
+    name: 'Custom_Interactive_Package', type: 'smd', pads: [], tracks: [], holes: [],
+    circles: [], arcs: [], rects: [], texts: [], vias: [], solidRegions: [],
+    origin: { x: 0, y: 0 },
+  },
+  model3d: {
+    name: 'Interactive Part', uuid: 'interactive-model',
+    translation: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0 },
+  },
+  rawData: {},
+};
+const community: EasyEDACommunityComponent = {
+  uuid: '8007c710c0b9406db963b55df6990340', title: 'Community Part',
+  description: 'Interactive community component', tags: [],
+  owner: { uuid: 'owner', username: 'owner', nickname: 'Community' },
+  updateTime: 0, docType: 2, verify: true,
+  symbol: { ...component.symbol, head: {} },
+  footprint: { ...component.footprint, uuid: 'footprint', head: {} },
+  model3d: component.model3d, rawData: {},
+};
+const model = Buffer.from('ISO-10303-21;\nEND-ISO-10303-21;');
+spyOn(easyedaClient, 'getComponentData').mockImplementation(async () => structuredClone(component));
+spyOn(easyedaClient, 'get3DModel').mockResolvedValue(model);
+spyOn(jlcClient, 'getComponentDetails').mockResolvedValue(null);
+spyOn(jlcClient, 'search').mockResolvedValue([{
+  id: 'C400', idType: 'lcsc', lcscId: 'C400', name: 'Interactive Part',
+  manufacturer: 'Maker', description: 'Interactive component', package: component.footprint.name,
+  stock: 10, libraryType: 'basic',
+}]);
+spyOn(easyedaCommunityClient, 'getComponent').mockImplementation(async () => structuredClone(community));
+spyOn(easyedaCommunityClient, 'get3DModel').mockResolvedValue(model);
+spyOn(easyedaCommunityClient, 'search').mockResolvedValue([{
+  uuid: community.uuid, title: community.title, description: community.description,
+  owner: community.owner, thumb: '', tags: [], package: community.footprint.name,
+  has3DModel: true, docType: 2,
+}]);
+mock.module('@clack/prompts', () => ({ text: async () => 'interactive', isCancel: () => false }));
+
+const terminal = createTerminal();
+const { see, key, output } = terminal;
+// Dynamic imports keep application/command initialization behind this subprocess's mock boundaries.
+const app = await import('../App.js');
+// Preserve the real App, screens, navigation and core services; only supply isolated terminal streams.
+mock.module('../App.js', () => ({
+  ...app,
+  renderApp: async (screen: ScreenName, params: ScreenParams[ScreenName]) => {
+    const instance = terminal.render(<app.App initialScreen={screen} initialParams={params} />);
+    await instance.waitUntilExit();
+  },
+}));
+const service = createLibraryService();
+try {
+  if (scenario === 'lcsc') {
+    // A pre-existing symbol exercises force (without it the customized footprint stays untouched).
+    const global = await service.install('C400', { include3d: false });
+    const local = await service.install('C400', { projectPath, include3d: false });
+    const globalSymbol = await readFile(global.files.symbolLibrary, 'utf8');
+    const globalFootprint = await readFile(global.files.footprint!, 'utf8');
+    await writeFile(local.files.footprint!, '(footprint "User customization")');
+    const { installCommand } = await import('../../commands/install.js');
+    const command = installCommand(undefined, { projectPath, force: true, include3d: true });
+    await see('Search:');
+    key('\r');
+    await see('Enter Install');
+    key('\r');
+    await see('Installed C400');
+
+    const footprint = await readFile(local.files.footprint!, 'utf8');
+    assert.ok(!footprint.includes('User customization'));
+    const modelReference = footprint.match(/\(model\s+"([^"]+)"/)?.[1];
+    assert.ok(modelReference?.startsWith('${KIPRJMOD}/libraries/3dmodels/'));
+    assert.deepEqual(await readFile(modelReference!.replace('${KIPRJMOD}', projectPath)), model);
+    assert.equal(await readFile(global.files.symbolLibrary, 'utf8'), globalSymbol);
+    assert.equal(await readFile(global.files.footprint!, 'utf8'), globalFootprint);
+    assert.equal(existsSync(getLibraryPaths().models3dFullDir), false);
+    const installed = await service.listInstalled({ projectPath });
+    assert.equal(installed.find(part => part.lcscId === 'C400')?.symbolRef, local.symbolRef);
+
+    key('\u001b');
+    await see('Enter Install');
+    key('\u001b');
+    await see('Search:');
+    key('q');
+    await command;
+  } else {
+    const global = await service.install(community.uuid, { include3d: true });
+    const globalSymbol = await readFile(global.files.symbolLibrary, 'utf8');
+    const globalFootprint = await readFile(global.files.footprint!, 'utf8');
+    assert.equal(await service.isEasyEDAInstalled(community.title), true);
+    assert.equal(await service.isEasyEDAInstalled(community.title, projectPath), false);
+    const { easyedaInstallCommand } = await import('../../commands/easyeda.js');
+    const command = easyedaInstallCommand(undefined, { projectPath, force: true, include3d: false });
+    await see('Search:');
+    key('\r');
+    // The global installation must not hide the selected project's install affordance.
+    await see('Enter Install');
+    assert.ok(!output().includes('R Regenerate'));
+    key('\r');
+    await see('Installed: EasyEDA-local:Community_Part');
+    const paths = getLibraryPaths(projectPath);
+    const symbolPath = join(paths.symbolsDir, 'EasyEDA-local.kicad_sym');
+    const footprintPath = join(paths.footprintsDir, 'EasyEDA-local.pretty', 'Community_Part.kicad_mod');
+    assert.ok((await readFile(symbolPath, 'utf8')).includes('(symbol "Community_Part"'));
+    const initialFootprint = await readFile(footprintPath, 'utf8');
+    assert.ok(!initialFootprint.includes('(model '));
+    assert.equal(existsSync(paths.models3dDir), false);
+
+    await writeFile(footprintPath, '(footprint "User customization")');
+    key('\r');
+    await see('Installed: EasyEDA-local:Community_Part');
+    assert.equal(await readFile(footprintPath, 'utf8'), initialFootprint);
+    assert.equal(existsSync(paths.models3dDir), false);
+    assert.equal(await readFile(global.files.symbolLibrary, 'utf8'), globalSymbol);
+    assert.equal(await readFile(global.files.footprint!, 'utf8'), globalFootprint);
+    assert.deepEqual(await readFile(global.files.model3d!), model);
+    assert.ok((await readFile(join(projectPath, 'sym-lib-table'), 'utf8')).includes('EasyEDA-local'));
+    key('\u001b');
+    await see('Search:');
+    key('q');
+    await command;
+  }
+} finally {
+  terminal.cleanup();
+}

package/src/app/__fixtures__/navigation-scenarios.tsx

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import { setTimeout as delay } from 'node:timers/promises';
+import { mock } from 'bun:test';
+import React from 'react';
+import { createTerminal } from './terminal.js';
+import * as core from '@jlcpcb/core';
+import type { SearchOptions } from '@jlcpcb/core';
+
+const scenario = process.argv[2];
+const part = {
+  id: 'C123', idType: 'lcsc' as const, lcscId: 'C123', name: 'Original Part',
+  manufacturer: 'Maker', description: 'A component', package: 'SOT-23',
+  stock: 10, libraryType: 'extended' as const,
+};
+const basic = { ...part, id: 'C124', lcscId: 'C124', name: 'Filtered Part', libraryType: 'basic' as const };
+let librariesReady = !scenario.startsWith('setup-');
+let finishSetup: () => void;
+const pendingSetup = new Promise<void>((resolve) => { finishSetup = resolve; });
+mock.module('@jlcpcb/core', () => ({
+  ...core,
+  createComponentService: () => ({
+    search: async (query: string, options: SearchOptions) => {
+      if (query.startsWith('C')) return [query === 'C124' ? basic : part];
+      // Changing source, stock or page size changes visible backend results.
+      if (options.source !== 'lcsc' || !options.inStock || options.limit !== 7) return [part];
+      return options.basicOnly ? [basic] : [part, basic];
+    },
+    getDetails: async () => part,
+  }),
+  createLibraryService: () => ({
+    getStatus: async () => ({ installed: librariesReady, linked: librariesReady }),
+    listInstalled: async () => [],
+    ensureGlobalTables: async () => {
+      if (scenario === 'setup-pending-back') await pendingSetup;
+      librariesReady = true;
+    },
+    install: async () => ({ symbolRef: 'JLC:Original_Part', footprintRef: 'JLC:SOT-23' }),
+  }),
+}));
+
+// Load the application only after installing this subprocess's service mocks.
+const { App } = await import('../App.js');
+const terminal = createTerminal();
+const { see, key, output } = terminal;
+terminal.render(
+  <App initialScreen="search" initialParams={{
+    query: 'parts', results: [part, basic],
+    searchOptions: { source: 'lcsc', inStock: true, limit: 7 },
+  }} />,
+);
+try {
+  await see('Search:');
+  if (scenario === 'filter-back') {
+    key('\t');
+    await see('1 results - Basic/Preferred only');
+    assert.ok(output().includes('Filtered Part'));
+    key('\r');
+    await see('Component:');
+    await see('Enter Install');
+    key('\u001b');
+    await see('1 results - Basic/Preferred only');
+    assert.ok(output().includes('Filtered Part'));
+    assert.ok(!output().includes('Original Part'));
+    key('\t');
+    await see('2 results');
+    assert.ok(output().includes('Original Part'));
+  } else {
+    key('\r');
+    await see('Component:');
+    await see('Enter Install');
+    key('\r');
+    if (scenario.startsWith('setup-')) {
+      await see('Library Setup Required');
+      if (scenario === 'setup-escape') {
+        key('\u001b');
+      } else {
+        key('\r');
+        if (scenario === 'setup-pending-back') {
+          await see('Setting Up Libraries');
+          key('\u001b');
+          await see('Component:');
+          // Settle the abandoned promise while details are active.
+          finishSetup!();
+          await delay(100);
+          assert.ok(!output().includes('Installing') && !output().includes('Installed'));
+        } else {
+          await see('Installed C123');
+          key(scenario === 'setup-complete-key' ? 'x' : '\u001b');
+        }
+      }
+    } else {
+      await see('Installed C123');
+      key(scenario === 'installed-key' ? 'x' : '\u001b');
+    }
+    await see('Component:');
+    await see('Enter Install');
+    assert.ok(!output().includes('Search:'));
+    key('\u001b');
+    await see('Search:');
+  }
+} finally {
+  terminal.cleanup();
+}

package/src/app/__fixtures__/terminal.tsx

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import { PassThrough, Writable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+import { stripVTControlCharacters } from 'node:util';
+import { render, type Instance } from 'ink';
+import type { ReactNode } from 'react';
+
+export function createTerminal() {
+  class Input extends PassThrough {
+    isTTY = true;
+    setRawMode() { return this; }
+    ref() { return this; }
+    unref() { return this; }
+  }
+  const stdin = new Input();
+  let output = '';
+  let instance: Instance | undefined;
+  const stdout = new Writable({
+    write(chunk, _encoding, callback) {
+      output += stripVTControlCharacters(String(chunk));
+      callback();
+    },
+  });
+  Object.assign(stdout, { columns: 120, rows: 40, isTTY: true });
+
+  return {
+    render(node: ReactNode) {
+      instance = render(node, {
+        stdin: stdin as unknown as NodeJS.ReadStream,
+        stdout: stdout as NodeJS.WriteStream,
+        stderr: stdout as NodeJS.WriteStream,
+        debug: true,
+        patchConsole: false,
+        exitOnCtrlC: false,
+      });
+      return instance;
+    },
+    async see(text: string) {
+      const deadline = Date.now() + 3_000;
+      while (!output.includes(text) && Date.now() < deadline) await delay(10);
+      assert.ok(output.includes(text), `Expected ${JSON.stringify(text)} in terminal output:\n${output}`);
+      // Let Ink commit its input subscriptions before sending the next key.
+      await delay(30);
+    },
+    key(value: string) {
+      output = '';
+      stdin.write(value);
+    },
+    output: () => output,
+    cleanup() {
+      instance?.unmount();
+      instance?.cleanup();
+      stdin.destroy();
+      stdout.destroy();
+    },
+  };
+}

package/src/app/components/DetailView.tsx

@@ -22,6 +22,7 @@ interface DetailViewProps {
   component: DetailViewComponent;
   terminalWidth: number;
   isInstalled?: boolean;
+  canInstall?: boolean;
   installedInfo?: InstalledComponent | null;
   statusMessage?: string | null;
 }
@@ -36,7 +37,7 @@ function truncate(str: string, len: number): string {
   return str.length > len ? str.slice(0, len - 1) + '…' : str;
 }
 
-export function DetailView({ component, terminalWidth, isInstalled, installedInfo, statusMessage }: DetailViewProps) {
+export function DetailView({ component, terminalWidth, isInstalled, canInstall = !isInstalled, installedInfo, statusMessage }: DetailViewProps) {
   const isWide = terminalWidth >= 80;
   const labelWidth = 16;
   // In wide mode, split into two columns with gap; otherwise full width
@@ -140,10 +141,12 @@ export function DetailView({ component, terminalWidth, isInstalled, installedInf
     </Box>
   ) : null;
 
-  // Footer text based on installation status
-  const footerText = isInstalled
-    ? 'R Regenerate • D Delete • O Datasheet • Esc Back'
-    : 'Enter Install • O Datasheet • Esc Back';
+  const footerText = [
+    ...(canInstall ? ['Enter Install'] : []),
+    ...(isInstalled ? ['R Regenerate', 'D Delete'] : []),
+    'O Datasheet',
+    'Esc Back',
+  ].join(' • ');
 
   return (
     <Box flexDirection="column" width="100%">

package/src/app/navigation/NavigationContext.tsx

@@ -37,7 +37,7 @@ export function NavigationProvider<T extends ScreenName>({
 
   const pop = useCallback(() => {
     if (currentIndex > 0) {
-      setCurrentIndex((prev) => prev - 1);
+      setCurrentIndex((prev) => Math.max(0, prev - 1));
       return true;
     }
     return false;

package/src/app/navigation/types.ts

@@ -1,4 +1,4 @@
-import type { ComponentSearchResult, ComponentDetails, InstallResult, InstalledComponent, LibraryStatus, EasyEDACommunityComponent } from '@jlcpcb/core';
+import type { ComponentSearchResult, ComponentDetails, InstallOptions, InstallResult, InstalledComponent, LibraryStatus, EasyEDACommunityComponent, SearchOptions } from '@jlcpcb/core';
 
 export type ScreenName = 'search' | 'info' | 'install' | 'library' | 'library-setup' | 'installed' | 'easyeda-info';
 
@@ -8,16 +8,21 @@ export type ComponentInfo = ComponentSearchResult | ComponentDetails;
 export interface SearchParams {
   query: string;
   results: ComponentSearchResult[];
+  searchOptions?: SearchOptions;
+  selectedIndex?: number;
+  installOptions?: InstallOptions;
 }
 
 export interface InfoParams {
   componentId: string;
   component?: ComponentInfo;
+  installOptions?: InstallOptions;
 }
 
 export interface InstallParams {
   componentId: string;
   component: ComponentInfo;
+  installOptions?: InstallOptions;
 }
 
 export interface LibraryParams {
@@ -28,6 +33,7 @@ export interface LibraryParams {
 export interface LibrarySetupParams {
   componentId: string;
   component: ComponentInfo;
+  installOptions?: InstallOptions;
 }
 
 export interface InstalledParams {
@@ -40,6 +46,7 @@ export interface InstalledParams {
 export interface EasyEDAInfoParams {
   uuid: string;
   component?: EasyEDACommunityComponent;
+  installOptions?: InstallOptions;
 }
 
 export interface ScreenParams {

package/src/app/navigation.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+describe('interactive navigation', () => {
+  for (const [scenario, behavior] of [
+    ['filter-back', 'preserves search constraints and filtered results across detail/back navigation'],
+    ['setup-escape', 'pops setup once on Escape'],
+    ['setup-complete-escape', 'returns to details on Escape after successful setup and install'],
+    ['setup-complete-key', 'returns to details on an ordinary key after successful setup and install'],
+    ['setup-pending-back', 'does not navigate after abandoned setup resolves'],
+    ['installed-escape', 'pops completion once on Escape'],
+    ['installed-key', 'retains ordinary-key completion navigation'],
+  ]) {
+    it(behavior, () => {
+      // Each real Ink render gets isolated services, module state and terminal streams.
+      const result = spawnSync(process.execPath, [join(import.meta.dir, '__fixtures__/navigation-scenarios.tsx'), scenario], {
+        encoding: 'utf8',
+        timeout: 15_000,
+      });
+      expect({ status: result.status, stderr: result.stderr }).toEqual({ status: 0, stderr: '' });
+    }, 20_000);
+  }
+});

package/src/app/screens/EasyEDAInfoScreen.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useState, useRef } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { createComponentService, createLibraryService, type EasyEDACommunityComponent } from '@jlcpcb/core';
-import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
+import { useCurrentScreen } from '../navigation/NavigationContext.js';
 import type { EasyEDAInfoParams } from '../navigation/types.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
 import { EasyEDADetailView } from '../components/EasyEDADetailView.js';
@@ -10,7 +10,6 @@ const componentService = createComponentService();
 const libraryService = createLibraryService();
 
 export function EasyEDAInfoScreen() {
-  const { replace } = useNavigation();
   const { params } = useCurrentScreen() as { screen: 'easyeda-info'; params: EasyEDAInfoParams };
   const { columns: terminalWidth } = useTerminalSize();
 
@@ -32,15 +31,14 @@ export function EasyEDAInfoScreen() {
       }
 
       try {
-        // Ensure global tables are set up
-        await libraryService.ensureGlobalTables();
+        if (!params.installOptions?.projectPath) await libraryService.ensureGlobalTables();
 
         // Fetch component
         const fetched = await componentService.fetchCommunity(params.uuid);
         if (fetched) {
           setComponent(fetched);
           // Check if already installed
-          const installed = await libraryService.isEasyEDAInstalled(fetched.title);
+          const installed = await libraryService.isEasyEDAInstalled(fetched.title, params.installOptions?.projectPath);
           setIsInstalled(installed);
         } else {
           setError('Component not found');
@@ -53,7 +51,7 @@ export function EasyEDAInfoScreen() {
     };
 
     init();
-  }, [params.uuid]);
+  }, [params.uuid, params.installOptions?.projectPath]);
 
   useInput((input, key) => {
     if (isLoading || !component || isInstalling) return;
@@ -67,7 +65,7 @@ export function EasyEDAInfoScreen() {
       setIsInstalling(true);
       setStatusMessage('Regenerating symbol and footprint...');
 
-      libraryService.install(params.uuid, { force: true })
+      libraryService.install(params.uuid, { ...params.installOptions, force: true })
         .then((result) => {
           setStatusMessage(`✓ Reinstalled: ${result.symbolRef}`);
           setIsInstalled(true);
@@ -92,8 +90,8 @@ export function EasyEDAInfoScreen() {
       setStatusMessage('Installing component...');
 
       // Ensure libraries are set up
-      libraryService.ensureGlobalTables()
-        .then(() => libraryService.install(params.uuid, {}))
+      (params.installOptions?.projectPath ? Promise.resolve() : libraryService.ensureGlobalTables())
+        .then(() => libraryService.install(params.uuid, params.installOptions))
         .then((result) => {
           if (result.symbolAction === 'exists') {
             setStatusMessage(`⚡ Already installed (use R to reinstall)`);

package/src/app/screens/InfoScreen.tsx

@@ -5,7 +5,7 @@ import open from 'open';
 import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
 import type { InfoParams, ComponentInfo } from '../navigation/types.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
-import { DetailView, type DetailViewComponent } from '../components/DetailView.js';
+import { DetailView } from '../components/DetailView.js';
 
 const componentService = createComponentService();
 const libraryService = createLibraryService();
@@ -33,16 +33,15 @@ export function InfoScreen() {
     const fetchData = async () => {
       setIsLoading(true);
       try {
-        // Fetch library status (for paths)
-        const status = await libraryService.getStatus();
-        setLibraryStatus(status);
+        if (!params.installOptions?.projectPath) {
+          const status = await libraryService.getStatus();
+          setLibraryStatus(status);
+        }
 
         // Check if already installed
-        const installed = await libraryService.listInstalled({});
+        const installed = await libraryService.listInstalled({ projectPath: params.installOptions?.projectPath });
         const found = installed.find(c => c.lcscId === componentId);
-        if (found) {
-          setInstalledInfo(found);
-        }
+        setInstalledInfo(found ?? null);
 
         // Fetch full details from API (always, to get price/stock/attributes)
         const searchResults = await componentService.search(componentId, { limit: 1 });
@@ -67,7 +66,7 @@ export function InfoScreen() {
     };
 
     fetchData();
-  }, [params.componentId, params.component]);
+  }, [params.componentId, params.component, params.installOptions?.projectPath]);
 
   // Get datasheet URL (different field names in different types)
   const datasheetUrl = component && ('datasheetPdf' in component ? component.datasheetPdf : 'datasheet' in component ? component.datasheet : undefined);
@@ -87,7 +86,7 @@ export function InfoScreen() {
       setIsRegenerating(true);
       setRegenerateMessage('Regenerating symbol and footprint...');
 
-      libraryService.install(componentLcscId, { force: true })
+      libraryService.install(componentLcscId, { ...params.installOptions, force: true })
         .then((result) => {
           setRegenerateMessage(`✓ Regenerated: ${result.symbolAction}`);
           // Clear message after 2 seconds
@@ -106,7 +105,7 @@ export function InfoScreen() {
       setIsDeleting(true);
       setRegenerateMessage('Deleting component...');
 
-      libraryService.remove(installedInfo.lcscId)
+      libraryService.remove(installedInfo.lcscId, { projectPath: params.installOptions?.projectPath })
         .then(() => {
           setRegenerateMessage('✓ Component deleted');
           setInstalledInfo(null);
@@ -126,8 +125,8 @@ export function InfoScreen() {
       return;
     }
 
-    // Enter - Install (only when not installed)
-    if (key.return && !installedInfo) {
+    // Explicit install commands may update an already-installed component.
+    if (key.return && (!installedInfo || params.installOptions)) {
       if (!componentLcscId) {
         setRegenerateMessage('✗ Missing LCSC part number');
         setTimeout(() => setRegenerateMessage(null), 3000);
@@ -138,11 +137,12 @@ export function InfoScreen() {
       checkingRef.current = true;
       setIsCheckingLibrary(true);
 
-      if (libraryStatus && (!libraryStatus.installed || !libraryStatus.linked)) {
+      if (!params.installOptions?.projectPath && libraryStatus && (!libraryStatus.installed || !libraryStatus.linked)) {
         // Libraries not set up - show setup screen
         push('library-setup', {
           componentId: componentLcscId,
           component,
+          installOptions: params.installOptions,
         });
         setIsCheckingLibrary(false);
         checkingRef.current = false;
@@ -151,6 +151,7 @@ export function InfoScreen() {
         push('install', {
           componentId: componentLcscId,
           component,
+          installOptions: params.installOptions,
         });
         setIsCheckingLibrary(false);
         checkingRef.current = false;
@@ -206,6 +207,7 @@ export function InfoScreen() {
         component={{ ...component, lcscId: componentLcscId }}
         terminalWidth={terminalWidth}
         isInstalled={!!installedInfo}
+        canInstall={!installedInfo || !!params.installOptions}
         installedInfo={installedInfo}
         statusMessage={regenerateMessage}
       />

package/src/app/screens/InstallScreen.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect } from 'react';
 import { Box, Text } from 'ink';
 import { createLibraryService, type InstallResult } from '@jlcpcb/core';
 import { useNavigation, useCurrentScreen } from '../navigation/NavigationContext.js';
@@ -10,14 +10,12 @@ export function InstallScreen() {
   const { replace } = useNavigation();
   const { params } = useCurrentScreen() as { screen: 'install'; params: InstallParams };
 
-  const [status, setStatus] = useState<'installing' | 'done'>('installing');
-
   useEffect(() => {
     let mounted = true;
 
     async function install() {
       try {
-        const result: InstallResult = await libraryService.install(params.componentId, {});
+        const result: InstallResult = await libraryService.install(params.componentId, params.installOptions);
         if (mounted) {
           replace('installed', {
             componentId: params.componentId,
@@ -41,7 +39,7 @@ export function InstallScreen() {
     return () => {
       mounted = false;
     };
-  }, [params.componentId, params.component, replace]);
+  }, [params.componentId, params.component, params.installOptions, replace]);
 
   return (
     <Box flexDirection="column">

package/src/app/screens/InstalledScreen.tsx

@@ -10,8 +10,8 @@ export function InstalledScreen() {
   const { params } = useCurrentScreen() as { screen: 'installed'; params: InstalledParams };
   const { columns: terminalWidth } = useTerminalSize();
 
-  useInput(() => {
-    pop();
+  useInput((_input, key) => {
+    if (!key.escape) pop();
   });
 
   const result = params.result