fix: auto-install @huggingface/transformers in non-TTY environments (#779)

* fix: auto-install @huggingface/transformers in non-TTY environments

Previously, promptInstall() immediately returned false in non-TTY
environments (CI, pipelines, automated agents), making embeddings
completely unavailable without manual intervention.

Now auto-installs the optional dependency with a log message when
running non-interactively. Falls back to the existing EngineError
if installation fails.

Closes #762

* fix: use --no-save for non-TTY auto-install, log failures, update JSDoc (#779)

- Add --no-save to non-TTY npm install to avoid mutating user package.json
- Log auto-install errors instead of silently swallowing them
- Update loadTransformers JSDoc to reflect new non-TTY behavior
- Update test assertion to match --no-save flag

Author: carlos-alm

src/domain/search/models.ts

@@ -96,13 +96,26 @@ export function getModelConfig(modelKey?: string): ModelConfig {
 }
 
 /**
- * Prompt the user to install a missing package interactively.
+ * Attempt to install a missing package.
+ * In TTY environments, prompts the user for confirmation first.
+ * In non-TTY environments (CI, piped stdin), installs automatically with a log message.
  * Returns true if the package was installed, false otherwise.
- * Skips the prompt entirely in non-TTY environments (CI, piped stdin).
  * @internal Not part of the public barrel.
  */
 export function promptInstall(packageName: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return Promise.resolve(false);
+  if (!process.stdin.isTTY) {
+    info(`Installing ${packageName} (optional dependency for semantic search)…`);
+    try {
+      execFileSync('npm', ['install', '--no-save', packageName], {
+        stdio: 'inherit',
+        timeout: 300_000,
+      });
+      return Promise.resolve(true);
+    } catch (err) {
+      info(`Auto-install failed: ${err instanceof Error ? err.message : String(err)}`);
+      return Promise.resolve(false);
+    }
+  }
 
   return new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -128,7 +141,7 @@ export function promptInstall(packageName: string): Promise<boolean> {
 /**
  * Lazy-load @huggingface/transformers.
  * If the package is missing, prompts the user to install it interactively.
- * In non-TTY environments, prints an error and exits.
+ * In non-TTY environments, attempts automatic installation.
  * @internal Not part of the public barrel.
  */
 export async function loadTransformers(): Promise<unknown> {

tests/unit/prompt-install.test.ts

@@ -34,12 +34,49 @@ describe('loadTransformers install prompt', () => {
     vi.restoreAllMocks();
   });
 
-  test('non-TTY: throws EngineError without prompting', async () => {
+  test('non-TTY: auto-installs without prompting', async () => {
     process.stdin.isTTY = undefined;
 
+    let importCount = 0;
     const rlFactory = vi.fn();
+    const execMock = vi.fn();
     vi.doMock('node:readline', () => ({ createInterface: rlFactory }));
-    vi.doMock('node:child_process', () => ({ execFileSync: vi.fn() }));
+    vi.doMock('node:child_process', () => ({ execFileSync: execMock }));
+    vi.doMock('@huggingface/transformers', () => {
+      importCount++;
+      if (importCount <= 1) throw new Error('Cannot find package');
+      return {
+        pipeline: async () => async (batch: string[]) => ({
+          data: new Float32Array(384 * batch.length),
+        }),
+        cos_sim: () => 0,
+      };
+    });
+
+    const { embed } = await import('../../src/domain/search/index.js');
+
+    const result = await embed(['test text'], 'minilm');
+    expect(result.vectors).toHaveLength(1);
+    expect(result.dim).toBe(384);
+    // readline should NOT have been called — no prompt in non-TTY
+    expect(rlFactory).not.toHaveBeenCalled();
+    // npm install should have been called automatically
+    expect(execMock).toHaveBeenCalledWith(
+      'npm',
+      ['install', '--no-save', '@huggingface/transformers'],
+      expect.objectContaining({ stdio: 'inherit', timeout: 300_000 }),
+    );
+  });
+
+  test('non-TTY: throws EngineError when auto-install fails', async () => {
+    process.stdin.isTTY = undefined;
+
+    const rlFactory = vi.fn();
+    const execMock = vi.fn(() => {
+      throw new Error('npm ERR!');
+    });
+    vi.doMock('node:readline', () => ({ createInterface: rlFactory }));
+    vi.doMock('node:child_process', () => ({ execFileSync: execMock }));
     vi.doMock('@huggingface/transformers', () => {
       throw new Error('Cannot find package');
     });
@@ -55,6 +92,8 @@ describe('loadTransformers install prompt', () => {
     });
     // readline should NOT have been called — no prompt in non-TTY
     expect(rlFactory).not.toHaveBeenCalled();
+    // npm install was attempted
+    expect(execMock).toHaveBeenCalled();
   });
 
   test('TTY + user declines: throws EngineError', async () => {