@arela/uploader 1.1.3 → 1.2.0

package/.claude/worktrees/agent-multi-profile/tests/unit/scoring-engine.test.js

@@ -0,0 +1,221 @@
+/**
+ * Tests for the best-match scoring engine (PROTOTYPE).
+ *
+ * Two layers:
+ *  1. Engine mechanics (pure): extension filter, required/negative
+ *     disqualification, weighted scoring, threshold, tie-breaking.
+ *  2. Faithfulness on representative documents: the seed matchers select the
+ *     same document type best-match would, including the key
+ *     `factura_inter_agencia` vs `factura_comercial` case resolved by SCORE
+ *     (not registration order).
+ */
+import { describe, it, expect } from '@jest/globals';
+
+import {
+  classifyDocument,
+  scoreMatcher,
+  selectBestMatch,
+} from '../../src/scoring/scoring-engine.js';
+import { scoringMatchers } from '../../src/scoring/matchers-seed.js';
+
+// ----------------------------- engine mechanics -----------------------------
+describe('scoreMatcher (mechanics)', () => {
+  const base = {
+    documentType: 't',
+    extensions: ['pdf'],
+    minScore: 2,
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+      { kind: 'CONTENT_REGEX', pattern: /beta/i, weight: 1 },
+    ],
+  };
+
+  it('returns null when the extension does not apply', () => {
+    expect(scoreMatcher(base, { source: 'alpha', extension: 'xml' })).toBeNull();
+  });
+
+  it('sums the weights of matched clues', () => {
+    const r = scoreMatcher(base, { source: 'alpha beta', extension: 'pdf' });
+    expect(r.score).toBe(3);
+    expect(r.totalWeight).toBe(3);
+    expect(r.fraction).toBeCloseTo(1);
+    expect(r.passed).toBe(true);
+  });
+
+  it('does not pass below minScore', () => {
+    const r = scoreMatcher(base, { source: 'beta', extension: 'pdf' });
+    expect(r.score).toBe(1);
+    expect(r.passed).toBe(false);
+  });
+
+  it('disqualifies on a negative clue hit', () => {
+    const m = {
+      ...base,
+      clues: [
+        { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+        { kind: 'CONTENT_REGEX', pattern: /excluded/i, negative: true },
+      ],
+    };
+    const r = scoreMatcher(m, { source: 'alpha excluded', extension: 'pdf' });
+    expect(r.disqualified).toBe(true);
+  });
+
+  it('disqualifies when a required clue is missing', () => {
+    const m = {
+      ...base,
+      clues: [
+        { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+        { kind: 'CONTENT_REGEX', pattern: /mandatory/i, required: true, weight: 1 },
+      ],
+    };
+    const r = scoreMatcher(m, { source: 'alpha', extension: 'pdf' });
+    expect(r.disqualified).toBe(true);
+  });
+});
+
+describe('selectBestMatch (ordering)', () => {
+  const ctx = { source: 'alpha beta gamma', extension: 'pdf' };
+  const low = {
+    documentType: 'low',
+    extensions: ['pdf'],
+    minScore: 1,
+    clues: [{ kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 1 }],
+  };
+  const high = {
+    documentType: 'high',
+    extensions: ['pdf'],
+    minScore: 1,
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 1 },
+      { kind: 'CONTENT_REGEX', pattern: /beta/i, weight: 1 },
+      { kind: 'CONTENT_REGEX', pattern: /gamma/i, weight: 1 },
+    ],
+  };
+
+  it('picks the highest score regardless of array order', () => {
+    expect(selectBestMatch([low, high], ctx).documentType).toBe('high');
+    expect(selectBestMatch([high, low], ctx).documentType).toBe('high');
+  });
+
+  it('breaks score ties by priority', () => {
+    const a = {
+      documentType: 'a',
+      extensions: ['pdf'],
+      minScore: 1,
+      priority: 0,
+      clues: [{ kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 }],
+    };
+    const b = { ...a, documentType: 'b', priority: 5 };
+    expect(selectBestMatch([a, b], ctx).documentType).toBe('b');
+  });
+});
+
+describe('qualify rules (group gate, OR-of-ANDs)', () => {
+  // mirrors factura_comercial: (cfdi>=2) OR (invoice>=1 AND customs>=1)
+  const m = {
+    documentType: 'q',
+    extensions: ['xml'],
+    qualify: [{ cfdi: 2 }, { invoice: 1, customs: 1 }],
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /cfdiA/i, group: 'cfdi' },
+      { kind: 'CONTENT_REGEX', pattern: /cfdiB/i, group: 'cfdi' },
+      { kind: 'CONTENT_REGEX', pattern: /factura/i, group: 'invoice' },
+      { kind: 'CONTENT_REGEX', pattern: /aduana/i, group: 'customs' },
+    ],
+  };
+
+  it('qualifies when a single rule is fully satisfied (cfdi>=2)', () => {
+    expect(scoreMatcher(m, { source: 'cfdiA cfdiB', extension: 'xml' }).passed).toBe(true);
+  });
+
+  it('qualifies on the AND rule (invoice AND customs)', () => {
+    expect(scoreMatcher(m, { source: 'factura aduana', extension: 'xml' }).passed).toBe(true);
+  });
+
+  it('does NOT qualify on a partial AND rule (customs alone)', () => {
+    // This is the COVE-acuse false-positive case the flat model produced.
+    const r = scoreMatcher(m, { source: 'aduana pedimento aduana', extension: 'xml' });
+    expect(r.passed).toBe(false);
+  });
+
+  it('does NOT qualify with only one cfdi marker', () => {
+    expect(scoreMatcher(m, { source: 'cfdiA', extension: 'xml' }).passed).toBe(false);
+  });
+});
+
+// --------------------------- faithfulness on docs ---------------------------
+const DOCS = {
+  simplificadoPaid: {
+    extension: 'pdf',
+    source: `FORMA SIMPLIFICADA DEL PEDIMENTO
+NUM. PEDIMENTO: 26 07 3429 6000079
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+RFC: CSM9204097Q1
+FECHA DE PAGO: 04/03/2026`,
+  },
+  simplificadoUnpaid: {
+    extension: 'pdf',
+    source: `FORMA SIMPLIFICADA DE PEDIMENTO
+NUM. PEDIMENTO: 26 07 3429 6000080
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+RFC: CSM9204097Q1
+*** NO PAGADO ***`,
+  },
+  completo: {
+    extension: 'pdf',
+    source: `NUM. PEDIMENTO: 26 07 3429 2002089
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+SEGUNDA COPIA TRANSPORTISTA
+CUADRO DE LIQUIDACION
+*** PAGO ELECTRONICO ***
+FECHA DE PAGO: 02/03/2026`,
+  },
+  interAgencia: {
+    extension: 'xml',
+    source: `<cfdi:Comprobante xmlns:cfdi="..." TipoDeComprobante="I">
+  <cfdi:Emisor Rfc="NAA120215F20"/>
+  <cfdi:Receptor Rfc="PCC1008161WA"/>
+  <cfdi:Concepto ClaveProdServ="78141502"/>
+</cfdi:Comprobante>`,
+  },
+};
+
+describe('seed matchers select the correct document type', () => {
+  it('classifies a paid simplificado', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.simplificadoPaid);
+    expect(r.detectedType).toBe('pedimento_simplificado');
+  });
+
+  it('resolves an unpaid simplificado to proforma (resolveType reused)', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.simplificadoUnpaid);
+    expect(r.detectedType).toBe('proforma');
+  });
+
+  it('separates completo from simplificado without registration order', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.completo);
+    expect(r.detectedType).toBe('pedimento_completo');
+  });
+});
+
+describe('inter-agencia precedence is by score, not order', () => {
+  it('wins over factura_comercial with the default seed', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.interAgencia);
+    expect(r.detectedType).toBe('factura_inter_agencia');
+    // factura_comercial also qualifies but scores far lower
+    const comercial = r.candidates.find(
+      (c) => c.documentType === 'factura_comercial',
+    );
+    const winner = r.candidates[0];
+    expect(winner.documentType).toBe('factura_inter_agencia');
+    if (comercial) expect(winner.score).toBeGreaterThan(comercial.score);
+  });
+
+  it('still wins when the matcher array is reversed (order-independent)', () => {
+    const reversed = [...scoringMatchers].reverse();
+    const r = classifyDocument(reversed, DOCS.interAgencia);
+    expect(r.detectedType).toBe('factura_inter_agencia');
+  });
+});

package/README.md

@@ -197,6 +197,71 @@ Display current configuration for all API targets and settings.
 arela config
 ```
 
+### `arela agent`
+
+Multi-profile polling agent: ONE process (one terminal) serves every tenant API,
+replacing the N `arela worker --poll` terminals (one per RFC×source folder with
+its own `.env`). Scan directories, tuning and scheduling live **server-side** in
+`pipeline_config`; the only local configuration is `profiles.json`.
+
+```bash
+arela agent                                  # uses ~/.arela/profiles.json
+arela agent --config ./profiles.json         # explicit config path
+arela agent --profile ktj,cem                # run a subset (debugging)
+arela agent --interval 10000                 # idle poll interval in ms
+```
+
+`~/.arela/profiles.json` (keep it private — it contains API keys):
+
+```jsonc
+{
+  "version": 1,
+  "serverId": "PALCO-01",                    // ONE id per machine; must match pipeline_config.serverId (or leave that null)
+  "pollIntervalMs": 5000,                    // optional
+  "logFile": "~/.arela/arela-agent.log",     // optional
+  "profiles": [
+    { "name": "ktj", "url": "https://ktj-api.example.com", "token": "ak_..." },
+    {
+      "name": "cem", "url": "https://cem-api.example.com", "token": "ak_...",
+      // Only for real cross-tenant jobs (sourceApi != targetApi):
+      "targets": { "agencia": { "baseUrl": "https://agencia-api.example.com", "token": "ak_..." } }
+    }
+  ]
+}
+```
+
+Behavior notes:
+
+- Jobs are processed **one at a time globally** (round-robin between profiles).
+  The config singleton and per-job env overrides make in-process parallelism
+  unsafe by design; if parallelism is ever needed, run child processes.
+- An unreachable tenant API backs off exponentially (30s → 10min) without
+  blocking the other profiles.
+- `Ctrl+C` waits for the in-flight job to finish before exiting, so jobs never
+  end up orphaned in RUNNING state.
+- While a long job runs, the OTHER profiles' `worker_status` may show OFFLINE
+  (no poll for >30s). Cosmetic: their jobs stay QUEUED and are picked up next.
+- Server-side setup per tenant: seed `pipeline_config` rows (one per RFC×source,
+  with `scanDirectories`, `extraOptions` tuning and schedule fields) and enable
+  the `PIPELINE_SCHEDULER` cronjob (`PUT /api/cronjobs`).
+
+### `arela agent init`
+
+Migration helper: reads the legacy per-folder `.env` files and generates
+`profiles.json` plus the `pipeline_config` seed payloads — locally, without
+calling any API (tokens never leave the machine).
+
+```bash
+arela agent init --from ../ktj-cli-maya ../ktj-cli-matro ../cem-cli-nas --server-id PALCO-01
+# Generates in ~/.arela/: profiles.json, seed-configs.json, seed-configs.sh
+```
+
+Folders pointing at the same tenant API collapse into one profile; each
+folder×RFC becomes a `pipeline_config` payload (`scheduleEnabled: false`
+initially). Review the generated files, run `bash ~/.arela/seed-configs.sh` to
+seed the server, then start `arela agent`. The old `.env` folders keep working
+during the migration — `arela worker --poll` is untouched.
+
 ### Global Options
 
 | Flag | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arela/uploader",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "CLI to upload files/directories to Arela",
   "bin": {
     "arela": "./src/index.js"

package/src/commands/AgentCommand.js

@@ -0,0 +1,210 @@
+import logger from '../services/LoggingService.js';
+import { PipelineApiService } from '../services/PipelineApiService.js';
+import { PipelineJobRunner } from '../services/PipelineJobRunner.js';
+import {
+  DEFAULT_PROFILES_PATH,
+  ProfileManager,
+} from '../services/ProfileManager.js';
+
+import appConfig from '../config/config.js';
+
+const BACKOFF_BASE_MS = 30_000;
+const BACKOFF_MAX_MS = 600_000;
+const SHUTDOWN_JOB_TIMEOUT_MS = 300_000;
+
+/**
+ * Agent Command Handler
+ * Multi-profile polling agent: ONE process (one terminal) replaces the N
+ * `arela worker --poll` terminals (one per RFC×source folder with its own .env).
+ * Profiles (tenant API url + token) come from profiles.json; everything else
+ * (scan directories, tuning, schedule) lives server-side in pipeline_config.
+ *
+ * Jobs are processed ONE AT A TIME globally: appConfig is a singleton and the
+ * job runner mutates process.env per job, so running two jobs concurrently
+ * would corrupt each other's configuration. If parallelism is ever needed,
+ * spawn child processes — never threads/promises inside this process.
+ *
+ * Usage:
+ *   arela agent
+ *   arela agent --config ./profiles.json --profile ktj,cem
+ */
+export class AgentCommand {
+  constructor() {
+    this.isShuttingDown = false;
+    this.activeJobPromise = null;
+    this.pollTimer = null;
+  }
+
+  /**
+   * Execute the agent command
+   * @param {Object} options - Command options
+   * @param {string} options.config - Path to profiles.json
+   * @param {string} options.interval - Base poll interval per round (ms)
+   * @param {string} options.profile - Comma-separated subset of profiles to run
+   */
+  async execute(options = {}) {
+    const agentConfig = ProfileManager.loadProfiles(
+      options.config || DEFAULT_PROFILES_PATH,
+    );
+
+    let profiles = agentConfig.profiles;
+    if (options.profile) {
+      const requested = options.profile
+        .split(',')
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean);
+      const known = new Set(profiles.map((p) => p.name));
+      const unknown = requested.filter((name) => !known.has(name));
+      if (unknown.length > 0) {
+        throw new Error(
+          `Unknown profile(s): ${unknown.join(', ')}. Available: ${[...known].join(', ')}`,
+        );
+      }
+      profiles = profiles.filter((p) => requested.includes(p.name));
+    }
+
+    const interval =
+      parseInt(options.interval) > 0
+        ? parseInt(options.interval)
+        : agentConfig.pollIntervalMs;
+
+    logger.setLogFilePath(agentConfig.logFile);
+
+    logger.info('🤖 Starting Arela Agent (multi-profile poll worker)');
+    logger.info(`🖥️  Server ID: ${agentConfig.serverId}`);
+    logger.info(`⏱️  Poll Interval: ${interval}ms`);
+    logger.info(`📒 Log file: ${agentConfig.logFile}`);
+
+    // One API client + job runner per profile, built once. PipelineApiService
+    // copies baseUrl/token at construction, so each instance stays bound to its
+    // profile even while applyProfile() reconfigures the singleton for others.
+    for (const profile of profiles) {
+      appConfig.applyProfile(profile);
+      profile.api = new PipelineApiService(profile.name);
+      profile.runner = new PipelineJobRunner(profile.api, agentConfig.serverId);
+      profile.failures = 0;
+      profile.backoffUntil = 0;
+      logger.info(`📡 Profile '${profile.name}' → ${profile.url}`);
+    }
+
+    this.#setupShutdownHandlers(profiles);
+
+    logger.success('Agent is running. Press Ctrl+C to stop.');
+
+    await this.#runLoop(profiles, agentConfig.serverId, interval);
+  }
+
+  /**
+   * Round-robin polling loop over all profiles
+   * @private
+   */
+  async #runLoop(profiles, serverId, interval) {
+    while (!this.isShuttingDown) {
+      let gotAnyJob = false;
+
+      for (const profile of profiles) {
+        if (this.isShuttingDown) break;
+        if (Date.now() < profile.backoffUntil) continue;
+
+        try {
+          // Reconfigure the singleton for THIS profile before polling/processing
+          appConfig.applyProfile(profile);
+          logger.setContext(profile.name);
+
+          const job = await profile.api.getNextJob(serverId, {
+            throwOnError: true,
+          });
+          profile.failures = 0;
+          profile.backoffUntil = 0;
+
+          if (job && job.id) {
+            gotAnyJob = true;
+            logger.info(
+              `📥 Got job: ${job.id} - ${job.type} for RFC ${job.rfc}`,
+            );
+            this.activeJobPromise = profile.runner.processJob(job);
+            await this.activeJobPromise;
+            this.activeJobPromise = null;
+          } else {
+            logger.debug('📭 No jobs available');
+          }
+        } catch (error) {
+          // A failing profile backs off exponentially but never kills the loop
+          profile.failures += 1;
+          const backoffMs = Math.min(
+            BACKOFF_BASE_MS * 2 ** (profile.failures - 1),
+            BACKOFF_MAX_MS,
+          );
+          profile.backoffUntil = Date.now() + backoffMs;
+          logger.error(
+            `Poll failed (attempt ${profile.failures}): ${error.message} — backing off ${Math.round(backoffMs / 1000)}s`,
+          );
+        } finally {
+          logger.setContext(null);
+        }
+      }
+
+      // One sleep per idle round (not one per profile)
+      if (!gotAnyJob && !this.isShuttingDown) {
+        await this.#sleep(interval);
+      }
+    }
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @private
+   */
+  #sleep(ms) {
+    return new Promise((resolve) => {
+      this.pollTimer = setTimeout(resolve, ms);
+    });
+  }
+
+  /**
+   * Setup graceful shutdown handlers
+   * @private
+   */
+  #setupShutdownHandlers(profiles) {
+    const shutdown = async (signal) => {
+      if (this.isShuttingDown) return;
+      this.isShuttingDown = true;
+
+      logger.setContext(null);
+      logger.info(`\n👋 Received ${signal}. Shutting down agent...`);
+
+      if (this.pollTimer) {
+        clearTimeout(this.pollTimer);
+      }
+
+      // Wait for the in-flight job so it ends COMPLETED/FAILED, never orphaned RUNNING
+      if (this.activeJobPromise) {
+        logger.info('⏳ Waiting for the current job to finish...');
+        await Promise.race([
+          this.activeJobPromise,
+          new Promise((resolve) =>
+            setTimeout(resolve, SHUTDOWN_JOB_TIMEOUT_MS),
+          ),
+        ]);
+      }
+
+      for (const profile of profiles) {
+        profile.api?.destroy();
+      }
+
+      logger.info('✅ Agent stopped gracefully');
+      logger.flush();
+      process.exit(0);
+    };
+
+    // The global SIGINT/SIGTERM handlers (index.js and LoggingService) call
+    // process.exit(0) immediately, which would kill the in-flight job mid-write.
+    // Agent mode owns shutdown: replace them with the graceful version.
+    process.removeAllListeners('SIGINT');
+    process.removeAllListeners('SIGTERM');
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+  }
+}
+
+export default new AgentCommand();