@iteratech/iteraocr-cli 0.1.7

package/README.md

@@ -0,0 +1,52 @@
+# IteraOCR CLI
+
+Terminal utility for folder-based OCR ingestion with IteraOCR.
+
+## Requirements
+
+- Node.js 20+
+- npm
+
+## Install
+
+After the package is published to npm:
+
+```bash
+npx @iteratech/iteraocr-cli start --config ./iteraocr-activation.json
+```
+
+Optional global install:
+
+```bash
+npm install -g @iteratech/iteraocr-cli
+iteraocr start --config ./iteraocr-activation.json
+```
+
+## Commands
+
+```bash
+iteraocr start [--config file] [--input dir] [--output dir] [--api-base-url url] [--api-key key] [--routing-preset fast|balanced|quality]
+iteraocr init [--config file] [--input dir] [--output dir] [--api-base-url url] [--api-key key] [--routing-preset fast|balanced|quality]
+iteraocr watch
+iteraocr status
+iteraocr reset [--yes]
+iteraocr help
+```
+
+## Activation
+
+The CLI does not contain customer-specific API addresses or keys.
+
+Those values come from:
+
+- `iteraocr-activation.json`, or
+- explicit CLI arguments such as `--api-base-url` and `--api-key`
+
+## Supported formats
+
+- `jpg`
+- `jpeg`
+- `png`
+- `tif`
+- `tiff`
+- `jp2`

package/bin/iteraocr.js

@@ -0,0 +1,808 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const readline = require('readline/promises');
+const { stdin, stdout } = require('process');
+const crypto = require('crypto');
+
+const APP_NAME = 'IteraOCR CLI';
+const HOME_DIR = process.env.ITERAOCR_HOME || path.join(os.homedir(), '.config', 'iteraocr');
+const CONFIG_PATH = path.join(HOME_DIR, 'config.json');
+const STATE_PATH = path.join(HOME_DIR, 'state.json');
+const DEFAULT_WORK_ROOT = path.join(os.homedir(), 'IteraOCR');
+const DEFAULT_INPUT_DIR = path.join(DEFAULT_WORK_ROOT, 'input');
+const DEFAULT_OUTPUT_DIR = path.join(DEFAULT_WORK_ROOT, 'output');
+const CHOICE_DEFAULT = '1';
+const CHOICE_CURRENT = '2';
+const CHOICE_CUSTOM = '3';
+const BURST_TIERS = [
+  { minQueued: 1000, batchSize: 400 },
+  { minQueued: 400, batchSize: 250 },
+  { minQueued: 150, batchSize: 125 }
+];
+const BURST_REQUEUE_THRESHOLD = 150;
+const SUPPORTED_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.tif', '.tiff', '.jp2']);
+const ROUTING_PRESETS = new Set(['fast', 'balanced', 'quality']);
+const DEFAULTS = {
+  header_name: 'x-api-key',
+  upload_path: '/v1/utility/upload-submit',
+  status_path_template: '/v1/gate/jobs/{job_id}',
+  result_path_template: '/v1/gate/jobs/{job_id}/result',
+  routing_preset: 'balanced',
+  batch_size: 50,
+  stable_delay_seconds: 10,
+  scan_interval_seconds: 5,
+  supported_extensions: ['jpg', 'jpeg', 'png', 'tif', 'tiff', 'jp2']
+};
+
+function printHelp() {
+  console.log(`${APP_NAME}\n`);
+  console.log('Commands:');
+  console.log('  iteraocr start [--config file] [--input dir] [--output dir] [--api-base-url url] [--api-key key] [--routing-preset fast|balanced|quality]');
+  console.log('  iteraocr init [--config file] [--input dir] [--output dir] [--api-base-url url] [--api-key key] [--routing-preset fast|balanced|quality]');
+  console.log('  iteraocr watch');
+  console.log('  iteraocr status');
+  console.log('  iteraocr reset [--yes]');
+  console.log('  iteraocr help');
+  console.log('\nDefaults:');
+  console.log(`  Input folder:  ${DEFAULT_INPUT_DIR}`);
+  console.log(`  Output folder: ${DEFAULT_OUTPUT_DIR}`);
+  console.log('  Or choose the current folder or a custom path during first-time setup.');
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+async function ensureHome() {
+  await fsp.mkdir(HOME_DIR, { recursive: true });
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    const raw = await fsp.readFile(filePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJson(filePath, payload) {
+  await ensureHome();
+  await fsp.writeFile(filePath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+}
+
+async function loadConfig() {
+  const config = await readJson(CONFIG_PATH, null);
+  if (!config) {
+    throw new Error('Config is missing. Run `iteraocr init` first.');
+  }
+  return { ...DEFAULTS, ...config };
+}
+
+async function loadState() {
+  const state = await readJson(STATE_PATH, { files: {}, jobs: {} });
+  normalizeState(state);
+  return state;
+}
+
+async function saveState(state) {
+  await writeJson(STATE_PATH, state);
+}
+
+function normalizeState(state) {
+  if (!state || typeof state !== 'object') {
+    return;
+  }
+  if (!state.files || typeof state.files !== 'object') {
+    state.files = {};
+  }
+  if (!state.jobs || typeof state.jobs !== 'object') {
+    state.jobs = {};
+  }
+  for (const entry of Object.values(state.files)) {
+    if (!entry || typeof entry !== 'object') {
+      continue;
+    }
+    if (entry.status === 'failed' && isQuotaRejected(entry.error || '')) {
+      entry.status = 'rejected';
+    }
+  }
+}
+
+function isQuotaRejected(detail) {
+  const message = String(detail || '');
+  return message.includes('monthly_limit_exceeded');
+}
+
+function markEntryRejected(entry, detail) {
+  entry.status = 'rejected';
+  entry.error = String(detail || 'request rejected');
+  entry.updatedAt = Date.now();
+}
+
+function markEntryFailed(entry, detail) {
+  entry.status = 'failed';
+  entry.error = String(detail || 'ocr failed');
+  entry.updatedAt = Date.now();
+}
+
+function normalizeRoutingPreset(value) {
+  const preset = String(value || 'balanced').trim().toLowerCase();
+  if (!ROUTING_PRESETS.has(preset)) {
+    throw new Error(`Invalid routing preset: ${value}`);
+  }
+  return preset;
+}
+
+async function promptIfMissing(question, currentValue) {
+  if (currentValue) {
+    return String(currentValue).trim();
+  }
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(`${question}: `);
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+function findActivationConfigCandidates() {
+  const candidates = [];
+  const names = ['iteraocr-activation.json', 'iteratech-activation.json'];
+  const roots = [process.cwd(), path.join(os.homedir(), 'Downloads')];
+  for (const root of roots) {
+    for (const name of names) {
+      const candidate = path.join(root, name);
+      if (fs.existsSync(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  }
+  return Array.from(new Set(candidates));
+}
+
+async function promptActivationConfigPath(currentValue) {
+  if (currentValue) {
+    return path.resolve(String(currentValue));
+  }
+  const candidates = findActivationConfigCandidates();
+  const suggested = candidates[0] || path.join(process.cwd(), 'iteraocr-activation.json');
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(`Aktivační konfigurace [${prettyPath(suggested)}]: `)).trim();
+    return path.resolve(expandUserPath(answer || suggested));
+  } finally {
+    rl.close();
+  }
+}
+
+function expandUserPath(value) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) {
+    return '';
+  }
+  if (trimmed === '~') {
+    return os.homedir();
+  }
+  if (trimmed.startsWith('~/')) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return trimmed;
+}
+
+function prettyPath(value) {
+  const home = os.homedir();
+  if (value.startsWith(`${home}${path.sep}`)) {
+    return `~${path.sep}${path.relative(home, value)}`;
+  }
+  return value;
+}
+
+async function promptPath(question, currentValue, defaultValue) {
+  const preset = currentValue ? expandUserPath(currentValue) : defaultValue;
+  if (currentValue) {
+    return path.resolve(preset);
+  }
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const currentDir = process.cwd();
+    while (true) {
+      console.log(`${question}:`);
+      console.log(`  ${CHOICE_DEFAULT}) Výchozí složka (${prettyPath(preset)})`);
+      console.log(`  ${CHOICE_CURRENT}) Aktuální složka (${prettyPath(currentDir)})`);
+      console.log(`  ${CHOICE_CUSTOM}) Vlastní cesta`);
+      const choice = (await rl.question(`Vyberte možnost [${CHOICE_DEFAULT}/${CHOICE_CURRENT}/${CHOICE_CUSTOM}] (Enter = ${CHOICE_DEFAULT}): `)).trim() || CHOICE_DEFAULT;
+
+      if (choice === CHOICE_DEFAULT) {
+        return path.resolve(preset);
+      }
+      if (choice === CHOICE_CURRENT) {
+        return path.resolve(currentDir);
+      }
+      if (choice === CHOICE_CUSTOM) {
+        const customValue = expandUserPath(await rl.question('Zadejte cestu ke složce: '));
+        if (customValue) {
+          return path.resolve(customValue);
+        }
+        console.log('Vlastní cesta nesmí být prázdná.');
+        continue;
+      }
+      console.log(`Neplatná volba: ${choice}`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function hasSetupOverrides(args) {
+  return Boolean(args.config || args.input || args.output || args['api-base-url'] || args['api-key'] || args['routing-preset']);
+}
+
+function configIsComplete(config) {
+  return Boolean(
+    config &&
+      String(config.api_base_url || '').trim() &&
+      String(config.api_key || '').trim() &&
+      String(config.input_dir || '').trim() &&
+      String(config.output_dir || '').trim()
+  );
+}
+
+function assertDistinctFolders(inputDir, outputDir) {
+  const resolvedInput = path.resolve(String(inputDir || ''));
+  const resolvedOutput = path.resolve(String(outputDir || ''));
+  if (resolvedInput && resolvedOutput && resolvedInput === resolvedOutput) {
+    throw new Error('Input and output folders must be different.');
+  }
+}
+
+function createTimeoutSignal(ms, extraSignals = []) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort(new Error(`request timed out after ${ms}ms`));
+  }, ms);
+  const cleanups = [];
+  const abortFrom = (source) => {
+    if (!source) {
+      return;
+    }
+    if (source.aborted) {
+      controller.abort(source.reason || new Error('request aborted'));
+      return;
+    }
+    const handler = () => controller.abort(source.reason || new Error('request aborted'));
+    source.addEventListener('abort', handler, { once: true });
+    cleanups.push(() => source.removeEventListener('abort', handler));
+  };
+  for (const source of extraSignals) {
+    abortFrom(source);
+  }
+  controller.signal.addEventListener(
+    'abort',
+    () => {
+      clearTimeout(timeout);
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+    },
+    { once: true }
+  );
+  return controller;
+}
+
+async function collectInitConfig(args) {
+  let fromConfig = {};
+  if (args.config) {
+    const activationPath = await promptActivationConfigPath(String(args.config));
+    fromConfig = await readJson(activationPath, {});
+  } else if (!args['api-base-url'] && !args['api-key']) {
+    const activationPath = await promptActivationConfigPath('');
+    fromConfig = await readJson(activationPath, {});
+  }
+  const merged = {
+    ...DEFAULTS,
+    ...fromConfig,
+    api_base_url: String(args['api-base-url'] || fromConfig.api_base_url || '').trim().replace(/\/$/, ''),
+    api_key: String(args['api-key'] || fromConfig.api_key || '').trim(),
+    routing_preset: normalizeRoutingPreset(args['routing-preset'] || fromConfig.routing_preset || DEFAULTS.routing_preset),
+    input_dir: String(args.input || fromConfig.input_dir || '').trim(),
+    output_dir: String(args.output || fromConfig.output_dir || '').trim()
+  };
+  return merged;
+}
+
+async function cmdInit(args, options = {}) {
+  const merged = await collectInitConfig(args);
+  merged.api_base_url = await promptIfMissing('OCR service base URL', merged.api_base_url);
+  merged.api_key = await promptIfMissing('API key', merged.api_key);
+  merged.input_dir = await promptPath('Input folder', merged.input_dir, DEFAULT_INPUT_DIR);
+  merged.output_dir = await promptPath('Output folder', merged.output_dir, DEFAULT_OUTPUT_DIR);
+
+  if (!merged.api_base_url || !merged.api_key) {
+    throw new Error('API base URL and API key are required.');
+  }
+  assertDistinctFolders(merged.input_dir, merged.output_dir);
+
+  await fsp.mkdir(merged.input_dir, { recursive: true });
+  await fsp.mkdir(merged.output_dir, { recursive: true });
+  await writeJson(CONFIG_PATH, merged);
+  console.log(`Saved configuration to ${CONFIG_PATH}`);
+  console.log(`Input folder ready at ${merged.input_dir}`);
+  console.log(`Output folder ready at ${merged.output_dir}`);
+  if (!options.skipNextStepHint) {
+    console.log('Run `iteraocr start` to begin automatic processing.');
+  }
+}
+
+function fileFingerprint(relPath, stats) {
+  return crypto.createHash('sha1').update(`${relPath}|${stats.size}|${stats.mtimeMs}`).digest('hex').slice(0, 16);
+}
+
+async function walkFiles(rootDir) {
+  const out = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = await fsp.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!SUPPORTED_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        continue;
+      }
+      out.push(fullPath);
+    }
+  }
+  return out.sort();
+}
+
+async function scanInput(config, state) {
+  const now = Date.now();
+  const inputDir = path.resolve(config.input_dir);
+  const files = await walkFiles(inputDir);
+  for (const filePath of files) {
+    const stats = await fsp.stat(filePath);
+    const relPath = path.relative(inputDir, filePath);
+    const current = state.files[filePath];
+    const stableAfter = now + config.stable_delay_seconds * 1000;
+    if (!current) {
+      state.files[filePath] = {
+        relPath,
+        size: stats.size,
+        mtimeMs: Math.round(stats.mtimeMs),
+        status: 'discovering',
+        firstSeenTs: now,
+        stableAfterTs: stableAfter,
+        updatedAt: now,
+        itemId: null,
+        jobId: null,
+        outputPath: null,
+        error: null
+      };
+      continue;
+    }
+    const changed = current.size !== stats.size || current.mtimeMs !== Math.round(stats.mtimeMs);
+    if (changed) {
+      Object.assign(current, {
+        relPath,
+        size: stats.size,
+        mtimeMs: Math.round(stats.mtimeMs),
+        status: 'discovering',
+        stableAfterTs: stableAfter,
+        updatedAt: now,
+        itemId: null,
+        jobId: null,
+        outputPath: null,
+        error: null
+      });
+      continue;
+    }
+    if (current.status === 'discovering' && current.stableAfterTs <= now) {
+      current.status = 'queued';
+      current.updatedAt = now;
+    }
+  }
+}
+
+function queuedEntries(state, batchSize) {
+  return Object.entries(state.files)
+    .filter(([, item]) => item.status === 'queued')
+    .sort((a, b) => a[1].updatedAt - b[1].updatedAt)
+    .slice(0, batchSize);
+}
+
+function queuedCount(state) {
+  return Object.values(state.files).filter((item) => item.status === 'queued').length;
+}
+
+function selectBatchSize(config, queued) {
+  for (const tier of BURST_TIERS) {
+    if (queued >= tier.minQueued) {
+      return tier.batchSize;
+    }
+  }
+  return Number(config.batch_size || 50);
+}
+
+function shouldStayInBurstMode(queued) {
+  return queued >= BURST_REQUEUE_THRESHOLD;
+}
+
+function authHeaderName(config) {
+  return String(config.header_name || 'x-api-key');
+}
+
+async function submitBatch(config, state, batchSize, abortSignal) {
+  const queued = queuedEntries(state, batchSize);
+  if (!queued.length) {
+    return { accepted: 0, attempted: 0, batchSize };
+  }
+
+  const form = new FormData();
+  form.append('routing_preset', normalizeRoutingPreset(config.routing_preset));
+  for (const [filePath, entry] of queued) {
+    const buffer = await fsp.readFile(filePath);
+    const itemId = `item-${fileFingerprint(entry.relPath, { size: entry.size, mtimeMs: entry.mtimeMs })}`;
+    form.append('item_ids', itemId);
+    form.append('relative_paths', entry.relPath);
+    const mime = mimeType(filePath);
+    form.append('files', new Blob([buffer], { type: mime }), path.basename(filePath));
+    entry.itemId = itemId;
+  }
+
+  const timeoutController = createTimeoutSignal(30000, [abortSignal]);
+  const response = await fetch(new URL(config.upload_path, config.api_base_url), {
+    method: 'POST',
+    headers: {
+      [authHeaderName(config)]: config.api_key
+    },
+    body: form,
+    signal: timeoutController.signal
+  });
+
+    if (!response.ok) {
+      const detail = await response.text();
+      for (const [, entry] of queued) {
+        const message = `upload failed: http ${response.status} ${detail.slice(0, 200)}`;
+        if (isQuotaRejected(message)) {
+          markEntryRejected(entry, message);
+        } else {
+          markEntryFailed(entry, message);
+        }
+      }
+    return { accepted: 0, attempted: queued.length, batchSize };
+  }
+
+  const payload = await response.json();
+  const rejected = new Map((payload.rejected || []).map((item) => [String(item.item_id || ''), String(item.error || 'upload rejected')]));
+  const acceptedItems = new Map((payload.items || []).map((item) => [String(item.item_id || ''), item]));
+
+  for (const [, entry] of queued) {
+    if (rejected.has(entry.itemId)) {
+      const message = rejected.get(entry.itemId);
+      if (isQuotaRejected(message)) {
+        markEntryRejected(entry, message);
+      } else {
+        markEntryFailed(entry, message);
+      }
+      continue;
+    }
+    if (acceptedItems.has(entry.itemId)) {
+      entry.status = 'submitted';
+      entry.jobId = String(payload.job_id || '');
+      entry.updatedAt = Date.now();
+      state.jobs[entry.jobId] = {
+        status: 'submitted',
+        updatedAt: Date.now()
+      };
+    }
+  }
+
+  return { accepted: Number(payload.accepted || 0), attempted: queued.length, batchSize };
+}
+
+async function submitQueuedWork(config, state, abortSignal) {
+  let totalAccepted = 0;
+  let submittedJobs = 0;
+  let lastBatchSize = 0;
+  let burstMode = false;
+
+  while (true) {
+    const queued = queuedCount(state);
+    if (!queued) {
+      break;
+    }
+    const batchSize = selectBatchSize(config, queued);
+    lastBatchSize = batchSize;
+    burstMode = burstMode || batchSize > Number(config.batch_size || 50);
+    const result = await submitBatch(config, state, batchSize, abortSignal);
+    totalAccepted += result.accepted;
+    if (!result.attempted) {
+      break;
+    }
+    if (result.accepted > 0) {
+      submittedJobs += 1;
+    }
+    if (!shouldStayInBurstMode(queuedCount(state))) {
+      break;
+    }
+  }
+
+  return {
+    accepted: totalAccepted,
+    submittedJobs,
+    lastBatchSize,
+    burstMode
+  };
+}
+
+async function pollJobs(config, state, abortSignal) {
+  const outputDir = path.resolve(config.output_dir);
+  await fsp.mkdir(outputDir, { recursive: true });
+  const submittedJobs = Array.from(new Set(Object.values(state.files).filter((item) => item.status === 'submitted' && item.jobId).map((item) => item.jobId)));
+  for (const jobId of submittedJobs) {
+    const url = new URL(config.result_path_template.replace('{job_id}', encodeURIComponent(jobId)), config.api_base_url);
+    const timeoutController = createTimeoutSignal(30000, [abortSignal]);
+    const response = await fetch(url, {
+      headers: {
+        [authHeaderName(config)]: config.api_key
+      },
+      signal: timeoutController.signal
+    });
+    if (!response.ok) {
+      state.jobs[jobId] = { status: `poll_http_${response.status}`, updatedAt: Date.now() };
+      continue;
+    }
+    const payload = await response.json();
+    state.jobs[jobId] = {
+      status: String(payload.job?.status || 'unknown'),
+      updatedAt: Date.now()
+    };
+    for (const item of payload.items || []) {
+      const match = Object.entries(state.files).find(([, entry]) => entry.itemId === item.item_id && entry.jobId === jobId);
+      if (!match) {
+        continue;
+      }
+      const [filePath, entry] = match;
+      if (item.status === 'completed') {
+        const relPath = entry.relPath;
+        const text = String((item.response_body || {}).text || '');
+        const outputPath = path.join(outputDir, relPath).replace(/\.[^.]+$/, '.txt');
+        await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+        await fsp.writeFile(outputPath, text, 'utf-8');
+        entry.status = 'completed';
+        entry.outputPath = outputPath;
+        entry.error = null;
+        entry.updatedAt = Date.now();
+      } else if (item.status === 'error') {
+        const errorPath = path.join(outputDir, entry.relPath).replace(/\.[^.]+$/, '.error.json');
+        await fsp.mkdir(path.dirname(errorPath), { recursive: true });
+        await fsp.writeFile(errorPath, JSON.stringify({ error: item.error || 'ocr failed' }, null, 2) + '\n', 'utf-8');
+        markEntryFailed(entry, item.error || 'ocr failed');
+      }
+    }
+  }
+}
+
+function mimeType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.tif' || ext === '.tiff') return 'image/tiff';
+  if (ext === '.jp2') return 'image/jp2';
+  return 'application/octet-stream';
+}
+
+function summarize(state) {
+  const summary = { discovering: 0, queued: 0, submitted: 0, completed: 0, failed: 0, rejected: 0 };
+  for (const item of Object.values(state.files)) {
+    if (summary[item.status] !== undefined) {
+      summary[item.status] += 1;
+    }
+  }
+  return summary;
+}
+
+function printSummary(state) {
+  const summary = summarize(state);
+  console.log(`Nalezeno=${summary.discovering} Čeká=${summary.queued} Odesláno=${summary.submitted} Hotovo=${summary.completed} Odmítnuto=${summary.rejected} Chyba=${summary.failed}`);
+}
+
+async function cmdStatus() {
+  const config = await loadConfig();
+  const state = await loadState();
+  console.log(`Nastavení: ${CONFIG_PATH}`);
+  console.log(`OCR služba: ${config.api_base_url}`);
+  console.log(`Režim: ${normalizeRoutingPreset(config.routing_preset)}`);
+  console.log(`Vstup: ${config.input_dir}`);
+  console.log(`Výstup: ${config.output_dir}`);
+  printSummary(state);
+  const recentJobs = Object.entries(state.jobs)
+    .sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+    .slice(0, 10);
+  for (const [jobId, job] of recentJobs) {
+    console.log(`job ${jobId} ${job.status}`);
+  }
+}
+
+async function confirmReset(skipPrompt) {
+  if (skipPrompt) {
+    return true;
+  }
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question('Opravdu chcete vymazat nastavení utility a místní historii? [y/N]: ')).trim().toLowerCase();
+    return answer === 'y' || answer === 'yes' || answer === 'a' || answer === 'ano';
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdReset(args) {
+  const confirmed = await confirmReset(Boolean(args.yes));
+  if (!confirmed) {
+    console.log('Reset zrušen.');
+    return;
+  }
+  await Promise.allSettled([
+    fsp.rm(CONFIG_PATH, { force: true }),
+    fsp.rm(STATE_PATH, { force: true })
+  ]);
+  console.log('Nastavení utility a místní historie byly smazány.');
+  console.log('Vaše vstupní a výstupní soubory zůstaly beze změny.');
+  console.log('Příště spusťte `iteraocr start` a nastavte utilitu znovu.');
+}
+
+async function runWatch(config) {
+  if (!configIsComplete(config)) {
+    throw new Error('Configuration is incomplete. Run `iteraocr init` again.');
+  }
+  assertDistinctFolders(config.input_dir, config.output_dir);
+  console.log(`${APP_NAME} běží`);
+  console.log(`Vstupní složka: ${config.input_dir}`);
+  console.log(`Výstupní složka: ${config.output_dir}`);
+  console.log(`OCR služba: ${config.api_base_url}`);
+  console.log(`Režim: ${normalizeRoutingPreset(config.routing_preset)}`);
+  console.log('Ukončení: Ctrl+C');
+
+  let stop = false;
+  let shuttingDown = false;
+  let currentController = null;
+  const onSigint = () => {
+    if (shuttingDown) {
+      console.error('Vynucené ukončení.');
+      process.exit(130);
+    }
+    shuttingDown = true;
+    stop = true;
+    console.log('\nUkončuji…');
+    currentController?.abort(new Error('interrupted'));
+  };
+  const onSigterm = () => {
+    stop = true;
+    currentController?.abort(new Error('terminated'));
+  };
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  while (!stop) {
+    const state = await loadState();
+    currentController = new AbortController();
+    try {
+      await scanInput(config, state);
+      const queueBeforeSubmit = queuedCount(state);
+      const submitSummary = await submitQueuedWork(config, state, currentController.signal);
+      await pollJobs(config, state, currentController.signal);
+      await saveState(state);
+      const summary = summarize(state);
+      const stamp = new Date().toISOString();
+      console.log(
+        `[${stamp}] Přijato=${submitSummary.accepted} Úlohy=${submitSummary.submittedJobs} Dávka=${submitSummary.lastBatchSize || Number(config.batch_size || 50)} Režim=${submitSummary.burstMode ? 'rychlý' : 'běžný'} Čekalo=${queueBeforeSubmit} Čeká=${summary.queued} Odesláno=${summary.submitted} Hotovo=${summary.completed} Odmítnuto=${summary.rejected} Chyba=${summary.failed}`
+      );
+    } catch (error) {
+      if (currentController.signal.aborted && stop) {
+        break;
+      }
+      const detail = error?.cause?.message ? `${error.message || error} (${error.cause.message})` : String(error.message || error);
+      console.error(`Zpracování se nepodařilo: ${detail}`);
+    } finally {
+      currentController = null;
+    }
+    if (stop) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Number(config.scan_interval_seconds || 5) * 1000));
+  }
+  process.off('SIGINT', onSigint);
+  process.off('SIGTERM', onSigterm);
+  console.log('Ukončeno.');
+}
+
+async function cmdWatch() {
+  const config = await loadConfig();
+  await runWatch(config);
+}
+
+async function cmdStart(args) {
+  let config = null;
+  let needsSetup = hasSetupOverrides(args);
+  if (!needsSetup) {
+    try {
+      config = await loadConfig();
+      needsSetup = !configIsComplete(config);
+    } catch {
+      needsSetup = true;
+    }
+  }
+  if (needsSetup) {
+    console.log('První spuštění utility.');
+    console.log('Nejprve nastavíme aktivační soubor, vstupní složku a výstupní složku.\n');
+    await cmdInit(args, { skipNextStepHint: true });
+    config = await loadConfig();
+  }
+  await runWatch(config);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0] || 'start';
+  try {
+    if (command === 'help' || command === '--help' || command === '-h') {
+      printHelp();
+      return;
+    }
+    if (command === 'init') {
+      await cmdInit(args);
+      return;
+    }
+    if (command === 'start') {
+      await cmdStart(args);
+      return;
+    }
+    if (command === 'watch') {
+      await cmdWatch();
+      return;
+    }
+    if (command === 'status') {
+      await cmdStatus();
+      return;
+    }
+    if (command === 'reset') {
+      await cmdReset(args);
+      return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+  } catch (error) {
+    console.error(String(error.message || error));
+    process.exitCode = 1;
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@iteratech/iteraocr-cli",
+  "version": "0.1.7",
+  "description": "Terminal utility for IteraOCR folder ingestion",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "iteraocr": "bin/iteraocr.js"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin"
+  ],
+  "license": "UNLICENSED"
+}