i18nsmith 0.1.8 → 0.2.0

package/src/commands/review.ts

@@ -0,0 +1,228 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import type { Command } from 'commander';
+import { loadConfigWithMeta, Scanner, type ScanCandidate, type ScanSummary } from '@i18nsmith/core';
+
+interface ReviewCommandOptions {
+  config?: string;
+  json?: boolean;
+  limit?: number;
+  scanCalls?: boolean;
+}
+
+type ReviewAction = 'allow' | 'deny' | 'skip' | 'stop';
+
+const DEFAULT_CONFIG_PATH = 'i18n.config.json';
+const DEFAULT_LIMIT = 20;
+
+export function literalToRegexPattern(value: string): string {
+  const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return `^${escaped}$`;
+}
+
+function normalizeLimit(value?: number): number {
+  if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
+    return DEFAULT_LIMIT;
+  }
+  return Math.min(Math.max(1, Math.floor(value)), 200);
+}
+
+type BucketedScanSummary = ScanSummary & {
+  buckets?: {
+    needsReview?: ScanCandidate[];
+    skipped?: Array<{ reason: string }>;
+  };
+};
+
+function summarizeSkipReasons(skipped: Array<{ reason: string }>): string[] {
+  if (!skipped.length) {
+    return [];
+  }
+  const counts = new Map<string, number>();
+  for (const entry of skipped) {
+    counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([reason, count]) => `${reason}: ${count}`);
+}
+
+async function writeExtractionOverrides(
+  configPath: string,
+  allowPatterns: string[],
+  denyPatterns: string[]
+): Promise<{ allowAdded: number; denyAdded: number; wrote: boolean }> {
+  if (!allowPatterns.length && !denyPatterns.length) {
+    return { allowAdded: 0, denyAdded: 0, wrote: false };
+  }
+
+  const raw = await fs.readFile(configPath, 'utf-8');
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  const extraction = (typeof parsed.extraction === 'object' && parsed.extraction !== null)
+    ? (parsed.extraction as Record<string, unknown>)
+    : (parsed.extraction = {});
+
+  const allowList = Array.isArray(extraction.allowPatterns)
+    ? [...(extraction.allowPatterns as string[])]
+    : [];
+  const denyList = Array.isArray(extraction.denyPatterns)
+    ? [...(extraction.denyPatterns as string[])]
+    : [];
+
+  const allowAdded = appendUnique(allowList, allowPatterns);
+  const denyAdded = appendUnique(denyList, denyPatterns);
+
+  if (allowAdded === 0 && denyAdded === 0) {
+    return { allowAdded, denyAdded, wrote: false };
+  }
+
+  extraction.allowPatterns = allowList;
+  extraction.denyPatterns = denyList;
+
+  await fs.writeFile(configPath, JSON.stringify(parsed, null, 2));
+  return { allowAdded, denyAdded, wrote: true };
+}
+
+function appendUnique(target: string[], additions: string[]): number {
+  const seen = new Set(target);
+  let added = 0;
+  for (const next of additions) {
+    if (seen.has(next)) continue;
+    target.push(next);
+    seen.add(next);
+    added++;
+  }
+  return added;
+}
+
+function printCandidate(candidate: ScanCandidate) {
+  const location = `${candidate.filePath}:${candidate.position.line}:${candidate.position.column}`;
+  console.log(chalk.cyan(`\n${candidate.text}`));
+  console.log(chalk.gray(`  • Location: ${location}`));
+  console.log(chalk.gray(`  • Kind: ${candidate.kind}`));
+  if (candidate.context) {
+    console.log(chalk.gray(`  • Context: ${candidate.context}`));
+  }
+}
+
+async function promptAction(): Promise<ReviewAction> {
+  const { action } = await inquirer.prompt<{ action: ReviewAction }>([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'Choose an action for this string',
+      choices: [
+        { name: 'Always translate (add to allowPatterns)', value: 'allow' },
+        { name: 'Always skip (add to denyPatterns)', value: 'deny' },
+        { name: 'Skip for now', value: 'skip' },
+        { name: 'Stop reviewing', value: 'stop' },
+      ],
+    },
+  ]);
+  return action;
+}
+
+export function registerReview(program: Command) {
+  program
+    .command('review')
+    .description('Review borderline candidates and persist allow/deny overrides')
+    .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_PATH)
+    .option('--json', 'Print raw bucket data as JSON', false)
+    .option('--limit <n>', 'Limit the number of items per session (default: 20)', (value) => parseInt(value, 10))
+    .option('--scan-calls', 'Include translation call arguments', false)
+    .action(async (options: ReviewCommandOptions) => {
+      try {
+        const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
+        const scanner = new Scanner(config, { workspaceRoot: projectRoot });
+  const summary = scanner.scan({ scanCalls: options.scanCalls }) as BucketedScanSummary;
+  const buckets = summary.buckets ?? {};
+  const needsReview = buckets.needsReview ?? [];
+  const skipped = buckets.skipped ?? [];
+
+        if (options.json) {
+          console.log(JSON.stringify({ needsReview, skipped }, null, 2));
+          return;
+        }
+
+        if (!needsReview.length) {
+          console.log(chalk.green('No borderline candidates detected.'));
+          const reasons = summarizeSkipReasons(skipped);
+          if (reasons.length) {
+            console.log(chalk.gray('Most common skip reasons:'));
+            reasons.forEach((line) => console.log(chalk.gray(`  • ${line}`)));
+          }
+          return;
+        }
+
+        if (!process.stdout.isTTY || process.env.CI === 'true') {
+          console.log(chalk.red('Interactive review requires a TTY. Use --json for non-interactive output.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const limit = normalizeLimit(options.limit);
+        const queue = needsReview.slice(0, limit);
+        console.log(
+          chalk.blue(
+            `Reviewing ${queue.length} of ${needsReview.length} candidate${needsReview.length === 1 ? '' : 's'} (limit=${limit}).`
+          )
+        );
+
+        const allowPatterns: string[] = [];
+        const denyPatterns: string[] = [];
+
+        for (const candidate of queue) {
+          printCandidate(candidate);
+          const action = await promptAction();
+          if (action === 'stop') {
+            break;
+          }
+          if (action === 'skip') {
+            continue;
+          }
+          const pattern = literalToRegexPattern(candidate.text);
+          if (action === 'allow') {
+            allowPatterns.push(pattern);
+            console.log(chalk.green(`  → Queued ${pattern} for allowPatterns`));
+          } else if (action === 'deny') {
+            denyPatterns.push(pattern);
+            console.log(chalk.yellow(`  → Queued ${pattern} for denyPatterns`));
+          }
+        }
+
+        if (!allowPatterns.length && !denyPatterns.length) {
+          console.log(chalk.gray('No config changes requested.'));
+          return;
+        }
+
+        const { allowAdded, denyAdded, wrote } = await writeExtractionOverrides(
+          configPath,
+          allowPatterns,
+          denyPatterns
+        );
+
+        if (!wrote) {
+          console.log(chalk.gray('Patterns already existed; config unchanged.'));
+          return;
+        }
+
+        console.log(
+          chalk.green(
+            `Updated ${relativize(configPath)} (${allowAdded} allow, ${denyAdded} deny pattern${
+              allowAdded + denyAdded === 1 ? '' : 's'
+            } added).`
+          )
+        );
+      } catch (error) {
+        console.error(chalk.red('Review failed:'), (error as Error).message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+function relativize(filePath: string): string {
+  return path.relative(process.cwd(), filePath) || filePath;
+}

package/src/commands/sync-seed.test.ts

@@ -1,12 +1,19 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import { ensureCliBuilt } from '../test-helpers/ensure-cli-built';
+
+const CLI_PATH = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
 
 describe('sync --seed-target-locales', () => {
   let tempDir: string;
 
+  beforeAll(async () => {
+    await ensureCliBuilt(CLI_PATH);
+  });
+
   beforeEach(async () => {
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-seed-test-'));
     
@@ -55,9 +62,8 @@ export function App() {
   });
 
   const runCli = (args: string): string => {
-    const cliPath = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
     try {
-      return execSync(`node ${cliPath} ${args}`, {
+      return execSync(`node ${CLI_PATH} ${args}`, {
         cwd: tempDir,
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],

package/src/commands/sync.ts

@@ -13,11 +13,13 @@ import {
   createRenameMappingFile,
   type SyncSummary,
   type KeyRenameBatchSummary,
+  type SyncSelection,
 } from '@i18nsmith/core';
 import {
   printLocaleDiffs,
   writeLocaleDiffPatches,
 } from '../utils/diff-utils.js';
+import { applyPreviewFile, writePreviewFile } from '../utils/preview.js';
 import { SYNC_EXIT_CODES } from '../utils/exit-codes.js';
 
 interface SyncCommandOptions {
@@ -49,6 +51,9 @@ interface SyncCommandOptions {
   shapeDelimiter?: string;
   seedTargetLocales?: boolean;
   seedValue?: string;
+  previewOutput?: string;
+  selectionFile?: string;
+  applyPreview?: string;
 }
 
 function collectAssumedKeys(value: string, previous: string[] = []) {
@@ -90,26 +95,66 @@ export function registerSync(program: Command) {
     .option('--shape-delimiter <char>', 'Delimiter for key nesting (default: ".")', '.')
     .option('--seed-target-locales', 'Add missing keys to target locale files with empty or placeholder values', false)
     .option('--seed-value <value>', 'Value to use when seeding target locales (default: empty string)', '')
+    .option('--preview-output <path>', 'Write preview summary (JSON) to a file (implies dry-run)')
+    .option('--selection-file <path>', 'Path to JSON file with selected missing/unused keys to write (used with --write)')
+    .option('--apply-preview <path>', 'Apply a previously saved sync preview JSON file safely')
     .action(async (options: SyncCommandOptions) => {
+      if (options.applyPreview) {
+        const extraArgs: string[] = [];
+        if (options.selectionFile) {
+          extraArgs.push('--selection-file', options.selectionFile);
+        }
+        if (options.prune) {
+          extraArgs.push('--prune');
+        }
+        await applyPreviewFile('sync', options.applyPreview, extraArgs);
+        return;
+      }
+
       const interactive = Boolean(options.interactive);
       const diffEnabled = Boolean(options.diff || options.patchDir);
       const invalidateCache = Boolean(options.invalidateCache);
-      const diffRequested = diffEnabled || Boolean(options.json);
+      const previewMode = Boolean(options.previewOutput);
+      const diffRequested = diffEnabled || Boolean(options.json) || previewMode;
+
       if (interactive && options.json) {
         console.error(chalk.red('--interactive cannot be combined with --json output.'));
         process.exitCode = 1;
         return;
       }
 
-      console.log(
-        chalk.blue(
-          interactive
-            ? 'Interactive sync (dry-run first)...'
-            : options.write
-            ? 'Syncing locale files...'
-            : 'Checking locale drift...'
-        )
-      );
+      if (previewMode && interactive) {
+        console.error(chalk.red('--preview-output cannot be combined with --interactive.'));
+        process.exitCode = 1;
+        return;
+      }
+
+      const writeEnabled = Boolean(options.write) && !previewMode;
+      if (previewMode && options.write) {
+        console.log(
+          chalk.yellow('Preview requested; ignoring --write and running in dry-run mode.')
+        );
+      }
+      options.write = writeEnabled;
+
+      if (options.selectionFile && !options.write) {
+        console.error(chalk.red('--selection-file requires --write (or --apply-preview) to take effect.'));
+        process.exitCode = 1;
+        return;
+      }
+
+      const selectionFromFile = options.selectionFile
+        ? await loadSelectionFile(options.selectionFile)
+        : undefined;
+
+      const banner = previewMode
+        ? 'Generating sync preview...'
+        : interactive
+        ? 'Interactive sync (dry-run first)...'
+        : writeEnabled
+        ? 'Syncing locale files...'
+        : 'Checking locale drift...';
+      console.log(chalk.blue(banner));
 
       try {
         const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
@@ -202,11 +247,17 @@ export function registerSync(program: Command) {
           validateInterpolations: options.validateInterpolations,
           emptyValuePolicy: options.emptyValues === false ? 'fail' : undefined,
           assumedKeys: options.assume,
+          selection: selectionFromFile,
           diff: diffRequested,
           invalidateCache,
           targets: options.target,
         });
 
+        if (previewMode && options.previewOutput) {
+          const savedPath = await writePreviewFile('sync', summary, options.previewOutput);
+          console.log(chalk.green(`Preview written to ${path.relative(process.cwd(), savedPath)}`));
+        }
+
         // Show backup info if created
         if (summary.backup) {
           console.log(chalk.blue(`\n📦 ${summary.backup.summary}`));
@@ -685,6 +736,49 @@ async function runInteractiveSync(syncer: Syncer, options: SyncCommandOptions) {
   }
 }
 
+async function loadSelectionFile(filePath: string): Promise<SyncSelection> {
+  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  let raw: string;
+  try {
+    raw = await fs.readFile(resolvedPath, 'utf8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to read selection file at ${resolvedPath}: ${message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Selection file ${resolvedPath} contains invalid JSON: ${message}`);
+  }
+
+  const selection: SyncSelection = {};
+  const missing = (parsed as { missing?: unknown }).missing;
+  const unused = (parsed as { unused?: unknown }).unused;
+
+  if (Array.isArray(missing)) {
+    const normalized = missing.map((key) => String(key).trim()).filter(Boolean);
+    if (normalized.length) {
+      selection.missing = normalized;
+    }
+  }
+
+  if (Array.isArray(unused)) {
+    const normalized = unused.map((key) => String(key).trim()).filter(Boolean);
+    if (normalized.length) {
+      selection.unused = normalized;
+    }
+  }
+
+  if (!selection.missing?.length && !selection.unused?.length) {
+    throw new Error(`Selection file ${resolvedPath} must include at least one "missing" or "unused" entry.`);
+  }
+
+  return selection;
+}
+
 function printRenameBatchSummary(summary: KeyRenameBatchSummary) {
   console.log(
     chalk.green(

package/src/commands/transform.ts

@@ -6,6 +6,7 @@ import { loadConfigWithMeta } from '@i18nsmith/core';
 import { Transformer } from '@i18nsmith/transformer';
 import type { TransformSummary } from '@i18nsmith/transformer';
 import { printLocaleDiffs, writeLocaleDiffPatches } from '../utils/diff-utils.js';
+import { applyPreviewFile, writePreviewFile } from '../utils/preview.js';
 
 interface TransformOptions {
   config?: string;
@@ -17,6 +18,8 @@ interface TransformOptions {
   diff?: boolean;
   patchDir?: string;
   migrateTextKeys?: boolean;
+  previewOutput?: string;
+  applyPreview?: string;
 }
 
 const collectTargetPatterns = (value: string | string[], previous: string[]) => {
@@ -83,11 +86,30 @@ export function registerTransform(program: Command) {
     .option('--patch-dir <path>', 'Write locale diffs to .patch files in the specified directory')
     .option('--target <pattern...>', 'Limit scanning to specific files or glob patterns', collectTargetPatterns, [])
     .option('--migrate-text-keys', 'Migrate existing t("Text") calls to structured keys')
+    .option('--preview-output <path>', 'Write preview summary (JSON) to a file (implies dry-run)')
+    .option('--apply-preview <path>', 'Apply a previously saved transform preview JSON file safely')
     .action(async (options: TransformOptions) => {
+      if (options.applyPreview) {
+        await applyPreviewFile('transform', options.applyPreview);
+        return;
+      }
+
       const diffEnabled = Boolean(options.diff || options.patchDir);
-      console.log(
-        chalk.blue(options.write ? 'Running transform (write mode)...' : 'Planning transform (dry-run)...')
-      );
+      const previewMode = Boolean(options.previewOutput);
+      const diffRequested = diffEnabled || previewMode;
+      const writeEnabled = Boolean(options.write) && !previewMode;
+
+      if (previewMode && options.write) {
+        console.log(chalk.yellow('Preview requested; ignoring --write and running in dry-run mode.'));
+      }
+      options.write = writeEnabled;
+
+      const banner = previewMode
+        ? 'Generating transform preview...'
+        : writeEnabled
+        ? 'Running transform (write mode)...'
+        : 'Planning transform (dry-run)...';
+      console.log(chalk.blue(banner));
 
       try {
         const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
@@ -103,10 +125,15 @@ export function registerTransform(program: Command) {
         const summary = await transformer.run({
           write: options.write,
           targets: options.target,
-          diff: diffEnabled,
+          diff: diffRequested,
           migrateTextKeys: options.migrateTextKeys,
         });
 
+        if (previewMode && options.previewOutput) {
+          const savedPath = await writePreviewFile('transform', summary, options.previewOutput);
+          console.log(chalk.green(`Preview written to ${path.relative(process.cwd(), savedPath)}`));
+        }
+
         if (options.report) {
           const outputPath = path.resolve(process.cwd(), options.report);
           await fs.mkdir(path.dirname(outputPath), { recursive: true });

package/src/commands/translate/index.ts

@@ -4,6 +4,7 @@
 
 import chalk from 'chalk';
 import inquirer from 'inquirer';
+import path from 'path';
 import type { Command } from 'commander';
 import {
   DEFAULT_PLACEHOLDER_FORMATS,
@@ -19,6 +20,7 @@ import type { TranslateCommandOptions, TranslateSummary, ProviderSettings } from
 import { emitTranslateOutput, maybePrintEstimate } from './reporter.js';
 import { handleCsvExport, handleCsvImport } from './csv-handler.js';
 import { executeTranslations } from './executor.js';
+import { applyPreviewFile, writePreviewFile } from '../../utils/preview.js';
 
 // Re-export types for external use
 export * from './types.js';
@@ -98,7 +100,14 @@ export function registerTranslate(program: Command): void {
     .option('--strict-placeholders', 'Fail if translated output has placeholder mismatches (for CI)', false)
     .option('--export <path>', 'Export missing translations to a CSV file for external translation')
     .option('--import <path>', 'Import translations from a CSV file and merge into locale files')
+    .option('--preview-output <path>', 'Write preview summary (JSON) to a file (implies dry-run)')
+    .option('--apply-preview <path>', 'Apply a previously saved translate preview JSON file safely')
     .action(async (options: TranslateCommandOptions) => {
+      if (options.applyPreview) {
+        await applyPreviewFile('translate', options.applyPreview, ['--yes']);
+        return;
+      }
+
       // Handle CSV export mode
       if (options.export) {
         await handleCsvExport(options);
@@ -111,9 +120,14 @@ export function registerTranslate(program: Command): void {
         return;
       }
 
-      console.log(
-        chalk.blue(options.write ? 'Translating locale files...' : 'Planning translations (dry-run)...')
-      );
+      const previewMode = Boolean(options.previewOutput);
+      const writeEnabled = Boolean(options.write) && !previewMode;
+      if (previewMode && options.write) {
+        console.log(chalk.yellow('Preview requested; ignoring --write and running in dry-run mode.'));
+      }
+      options.write = writeEnabled;
+
+      console.log(chalk.blue(writeEnabled ? 'Translating locale files...' : 'Planning translations (dry-run)...'));
 
       try {
         const config = await loadConfig(options.config);
@@ -142,6 +156,12 @@ export function registerTranslate(program: Command): void {
         };
 
         if (!options.write) {
+          if (previewMode && options.previewOutput) {
+            const savedPath = await writePreviewFile('translate', summary, options.previewOutput);
+            console.log(chalk.green(`Preview written to ${path.relative(process.cwd(), savedPath)}`));
+            return;
+          }
+
           if (options.estimate && providerSettings.name !== 'manual') {
             await maybePrintEstimate(plan, providerSettings);
           }

package/src/commands/translate/types.ts

@@ -19,6 +19,8 @@ export interface TranslateCommandOptions {
   strictPlaceholders?: boolean;
   export?: string;
   import?: string;
+  previewOutput?: string;
+  applyPreview?: string;
 }
 
 export interface TranslateLocaleResult extends TranslationWriteSummary {

package/src/commands/translate.test.ts

@@ -1,12 +1,19 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import { ensureCliBuilt } from '../test-helpers/ensure-cli-built';
+
+const CLI_PATH = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
 
 describe('translate command', () => {
   let tempDir: string;
 
+  beforeAll(async () => {
+    await ensureCliBuilt(CLI_PATH);
+  });
+
   beforeEach(async () => {
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-translate-test-'));
     
@@ -55,9 +62,8 @@ export function App() {
   });
 
   const runCli = (args: string): string => {
-    const cliPath = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
     try {
-      return execSync(`node ${cliPath} ${args}`, {
+      return execSync(`node ${CLI_PATH} ${args}`, {
         cwd: tempDir,
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],

package/src/e2e.test.ts

@@ -9,6 +9,7 @@ import path from 'path';
 import os from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { ensureCliBuilt } from './test-helpers/ensure-cli-built';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -84,17 +85,8 @@ function extractJson<T>(output: string): T {
   return JSON.parse(jsonMatch[0]);
 }
 
-beforeAll(() => {
-  const cliRoot = path.resolve(__dirname, '..');
-  const result = spawnSync('pnpm', ['build'], {
-    cwd: cliRoot,
-    stdio: 'inherit',
-    env: { ...process.env },
-  });
-
-  if (result.status !== 0) {
-    throw new Error('Failed to build CLI before running E2E tests');
-  }
+beforeAll(async () => {
+  await ensureCliBuilt(CLI_PATH);
 });
 
 describe('E2E Fixture Tests', () => {

package/src/index.ts

@@ -15,6 +15,7 @@ import { registerBackup } from './commands/backup.js';
 import { registerRename } from './commands/rename.js';
 import { registerInstallHooks } from './commands/install-hooks.js';
 import { registerConfig } from './commands/config.js';
+import { registerReview } from './commands/review.js';
 
 export const program = new Command();
 
@@ -38,6 +39,7 @@ registerBackup(program);
 registerRename(program);
 registerInstallHooks(program);
 registerConfig(program);
+registerReview(program);
 
 
 program.parse();

package/src/integration.test.ts

@@ -3,17 +3,19 @@
  * These tests run the actual CLI commands against real file systems
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { ensureCliBuilt } from './test-helpers/ensure-cli-built';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Get the correct CLI path regardless of where tests are run from
+// During tests, __dirname points to src/, so we go up one level to find dist/
 const CLI_PATH = path.resolve(__dirname, '../dist/index.js');
 
 // Helper to run CLI commands
@@ -33,6 +35,11 @@ function runCli(
     },
   });
 
+  // Log errors for debugging
+  if (result.error) {
+    console.error('CLI execution error:', result.error);
+  }
+
   const stdout = result.stdout ?? '';
   const stderr = result.stderr ?? '';
 
@@ -56,6 +63,10 @@ function extractJson<T>(output: string): T {
 describe('CLI Integration Tests', () => {
   let tmpDir: string;
 
+  beforeAll(async () => {
+    await ensureCliBuilt(CLI_PATH);
+  });
+
   beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-cli-integration-'));
   });