@bytebrand/export-cars 1.26.31 → 1.26.33

package/src/configs/autouncle.config.ts

@@ -1,12 +1,60 @@
-import { ExportType, FileType, ImageType } from 'src/enums';
+import { toNumber } from 'lodash';
+
+import { ExportType, FileType, ImageType } from '../enums';
 import { Params } from '../interfaces/params.interface';
+import { FeedGuardOptions } from '../services/feed-guard';
 import { Config } from './config';
 
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+
+const positiveNumber = (value: unknown, fallback: number): number => {
+  const parsed = toNumber(text(value));
+  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+// Guard defaults. The PROD job only exports a dealer allow-list, so the published count is far below
+// the base snapshot: minPublishedItems only forbids an empty file — set a real minimum per job.
+export const AUTOUNCLE_DEFAULTS = {
+  imageConcurrency: 16,
+  minSourceItems: 1000,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * AutoUncle JSON feed (ADV-322/323): `{"ads":[...]}` with clean ADV-336 images.
+ * Dry-run is the default: the file goes to resources/autouncle-dryrun, which no Cronicle step reads.
+ * Only autouncleDryRun=false writes resources/autouncle-export (the path `3.1 … part 2` copies from).
+ * Each mode has its own guard state.
+ */
 export class AutouncleConfig extends Config {
+  dryRun: boolean;
+  imageConcurrency: number;
+  // 0 = no limit (no partner limit known)
+  maxImages: number;
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
   constructor(params: Params) {
     super(params);
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.AUTOUNCLE}-export`;
-    this.imageType = ImageType.default;
+    this.dryRun = text(params.autouncleDryRun).toLowerCase() !== 'false';
+    const mode = this.dryRun ? 'dryrun' : 'export';
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.AUTOUNCLE}-${mode}`;
+    this.stateDir = `resources/${ExportType.AUTOUNCLE}-state/${mode}`;
+    this.imageType = ImageType.clean;
+    this.imageConcurrency = positiveNumber(params.autouncleImageConcurrency, AUTOUNCLE_DEFAULTS.imageConcurrency);
+    this.maxImages = Math.floor(positiveNumber(params.autouncleMaxImages, 0));
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, AUTOUNCLE_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, AUTOUNCLE_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, AUTOUNCLE_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, AUTOUNCLE_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, AUTOUNCLE_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
     this.outputFiles = [
       `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.AUTOUNCLE}.${FileType.JSON}`,
     ];

package/src/configs/meinstadt.config.ts

@@ -1,12 +1,67 @@
+import { toNumber } from 'lodash';
+
 import { Params } from '../interfaces/params.interface';
+import { FeedGuardOptions } from '../services/feed-guard';
 import { Config } from './config';
 import { ExportType, FileType, ImageType } from '../enums';
 
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+
+const positiveNumber = (value: unknown, fallback: number): number => {
+  const parsed = toNumber(text(value));
+  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+// A CPC tariff as the Cronicle text param holds it: a positive decimal with a dot ("0.99").
+// Anything else (empty, 0, "0,08", "abc") counts as not configured.
+export const parseMeinstadtCpc = (value: unknown): string | null => {
+  const raw = text(value);
+  return /^\d+(\.\d+)?$/.test(raw) && Number(raw) > 0 ? raw : null;
+};
+
+// Same guard defaults as the OpenAI feed (prod-sized); DEV needs smaller minimums via the params.
+export const MEINSTADT_DEFAULTS = {
+  imageConcurrency: 16,
+  minSourceItems: 1000,
+  minPublishedItems: 500,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * meinestadt.de vehicle feed (ADV-325/326): JSON array + ZIP of it, clean ADV-336 images.
+ * Dry-run is the default: the files go to resources/meinstadt-dryrun, which no upload step reads.
+ * Only meinstadtDryRun=false writes resources/meinstadt-export (the path the Cronicle FTP step
+ * uploads from), and only with a configured cpc. Each mode has its own guard state.
+ */
 export class MeinstadtConfig extends Config {
+  dryRun: boolean;
+  imageConcurrency: number;
+  // 0 = no limit (no partner limit known)
+  maxImages: number;
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
   constructor(params: Params) {
     super(params);
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.MEINSTADT}-export`;
-    this.imageType = ImageType.default;
+    this.dryRun = text(params.meinstadtDryRun).toLowerCase() !== 'false';
+    const mode = this.dryRun ? 'dryrun' : 'export';
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.MEINSTADT}-${mode}`;
+    this.stateDir = `resources/${ExportType.MEINSTADT}-state/${mode}`;
+    this.imageType = ImageType.clean;
+    this.cpc = parseMeinstadtCpc(params.cpc);
+    this.imageConcurrency = positiveNumber(params.meinstadtImageConcurrency, MEINSTADT_DEFAULTS.imageConcurrency);
+    this.maxImages = Math.floor(positiveNumber(params.meinstadtMaxImages, 0));
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, MEINSTADT_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, MEINSTADT_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, MEINSTADT_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, MEINSTADT_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, MEINSTADT_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
     this.outputFiles = [
       `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MEINSTADT}.${FileType.JSON}`,
       `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MEINSTADT}.${FileType.ZIP}`,

package/src/constants/autouncle.contants.ts

@@ -1,4 +1,3 @@
 export const MIN_MILEAGES = 0;
-export const DEFAULT_ZIP = '';
-export const DEFAULT_CITY = '';
-export const DEFAULT_ADDR1 = '';
+// seller_region when the postal code table does not know the dealer's place
+export const DEFAULT_REGION = 'Deutschland';

package/src/exporters/autouncle.exporter.ts

@@ -1,16 +1,23 @@
-import { get } from 'lodash';
-
 import { Injectable } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 
-import { CronicleUtils } from '@bytebrand/cronicle-helper';
 import { FsChunkInterface } from '@bytebrand/chunkable';
+import { LoggerService } from '@bytebrand/cronicle-helper';
 
-import { AutouncleTransformer } from '../transformers/autouncle.transformer';
-import { AutouncleJsonBuilder } from '../formats/autouncle-json.builder';
-import { CarService, RulesService, LoaderService, ConfigService } from '../services';
+import { AutouncleTransformer, AutouncleAddress, toAutouncleImages } from '../transformers/autouncle.transformer';
+import { resolveOpenAiImageFields } from '../transformers/openai-image-fields';
+import { CarService, RulesService, LoaderService, ConfigService, ImagesService } from '../services';
+import { ImageUrlValidator } from '../services/image-url-validator.service';
+import { FeedGuard } from '../services/feed-guard';
+import { AutouncleFeedRun, AutouncleSourceCar } from '../services/autouncle-feed-run';
+import { AutouncleConfig } from '../configs/autouncle.config';
 import { Exporter } from '../interfaces/exporter.interface';
 
+/**
+ * ExportType.AUTOUNCLE (ADV-322/323). Wires the Cronicle/Nest services into AutouncleFeedRun, which
+ * holds the logic. The output directory is no longer emptied: the new JSON replaces the old one only
+ * after the fail-closed guard passed.
+ */
 @Injectable()
 export class AutouncleExporter implements Exporter {
   constructor(
@@ -18,43 +25,58 @@ export class AutouncleExporter implements Exporter {
     private configService: ConfigService,
     private loaderService: LoaderService,
     private rulesService: RulesService,
+    private imagesService: ImagesService,
     private moduleRef: ModuleRef,
   ) {}
 
   async export(): Promise<void> {
-    const [fileName] = this.configService.config.outputFiles;
-    await CronicleUtils.ensureDir(this.configService.config.pathesConfig.localConvertedDirectory);
-    await CronicleUtils.emptyDir(this.configService.config.pathesConfig.localConvertedDirectory);
-
-    const autouncleJsonBuilder = new AutouncleJsonBuilder(fileName);
-    await autouncleJsonBuilder.buildStart();
-
-    const autouncleTransformer = await this.moduleRef.create(AutouncleTransformer);
-
-    let firstCar = true;
-    await this.loaderService.process(async (chunk: FsChunkInterface) => {
-      chunk.data = chunk.data.filter(e => this.carService.filterCar(e, this.rulesService.rules));
+    const config = this.configService.config as AutouncleConfig;
+    const [jsonFile] = config.outputFiles;
+    const validator = new ImageUrlValidator({ concurrency: config.imageConcurrency });
+    const transformer = await this.moduleRef.create(AutouncleTransformer);
+    const addresses = new Map<string, Promise<AutouncleAddress | null>>();
 
-      for (const data of chunk.data) {
-        const ownerId = get(data.car, 'metaData.ownerId');
-        // NOTES:: it must be temporary solution
-        const owner = await this.carService.getOwner(ownerId).catch((error: any) => { console.error(error); return null; });
-        if (!owner) { console.log(`Skip car because owner ${ownerId} is not a dealer`); continue; }
-        // console.time(`Transform ${data.car._id}`);
-        const car = await autouncleTransformer.transform({ owner, ...data });
-        // console.timeEnd(`Transform ${data.car._id}`);
+    const run = new AutouncleFeedRun(
+      {
+        forEachChunk: fn => this.loaderService.process((chunk: FsChunkInterface) => fn(chunk.data as AutouncleSourceCar[])),
+        filterCar: source => this.carService.filterCar(source, this.rulesService.rules),
+        dealerAddress: (ownerId) => {
+          if (!addresses.has(ownerId)) {
+            addresses.set(ownerId, this.carService.getOwner(ownerId)
+              .then(owner => (owner ? transformer.getAddress(owner) : null))
+              .catch((error: any) => { console.error(error?.message ?? error); return null; }));
+          }
+          return addresses.get(ownerId);
+        },
+        resolveImages: async ({ car, images }) => toAutouncleImages(
+          await resolveOpenAiImageFields(this.imagesService.getCleanImages(car._id, images), validator),
+          config.maxImages,
+        ),
+        imageStats: () => validator.stats,
+        translate: key => transformer.translate(key),
+        guard: new FeedGuard(config.feedGuard),
+      },
+      {
+        runId: config.runId,
+        dryRun: config.dryRun,
+        domain: config.domain,
+        sourceDirectory: config.pathesConfig.localDirectory,
+        sourceBaseFileName: config.pathesConfig.baseFileName,
+        jsonFile,
+        stateDir: config.stateDir,
+      },
+    );
 
-        await autouncleJsonBuilder.addItem(car, firstCar);
-
-        this.carService.counter.countCar(data.images);
-
-        if (firstCar) {
-          firstCar = false;
-        }
+    try {
+      const report = await run.run();
+      if (report.stale) {
+        console.log(`autouncle feed STALE: last good file ${report.lastGoodAgeHours?.toFixed(1)} h old`);
       }
-    });
-
-    await autouncleJsonBuilder.buildEnd();
-    console.log(this.carService.counter.getCountedCars());
+    } catch (error) {
+      // main.ts would report a rejected run as {"complete":1,"code":0}; fail the job so the chained
+      // `3.1 … part 2` copy step does not run (report + lock already handled by the run).
+      LoggerService.exitError(`autouncle feed not published: ${error?.message ?? error}`);
+      process.exit(1);
+    }
   }
 }

package/src/exporters/meinstadt.exporter.ts

@@ -1,16 +1,23 @@
 import { Injectable } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 
-import { CronicleUtils } from '@bytebrand/cronicle-helper';
 import { FsChunkInterface } from '@bytebrand/chunkable';
-import { Zipper } from '@bytebrand/zipper';
+import { LoggerService } from '@bytebrand/cronicle-helper';
 
-import { CarService, RulesService, LoaderService, ConfigService } from '../services';
-import { MeinstadtTransformer } from '../transformers/meinstadt.transformer';
-import { MeinstadtJsonBuilder } from '../formats/meinstadt-json.builder';
-import { MeinstadtJsonItem } from '../interfaces';
+import { CarService, RulesService, LoaderService, ConfigService, ImagesService } from '../services';
+import { ImageUrlValidator } from '../services/image-url-validator.service';
+import { FeedGuard } from '../services/feed-guard';
+import { MeinstadtFeedRun, MeinstadtSourceCar, zipSingleFile } from '../services/meinstadt-feed-run';
+import { MeinstadtTransformer, toMeinstadtImages } from '../transformers/meinstadt.transformer';
+import { resolveOpenAiImageFields } from '../transformers/openai-image-fields';
+import { MeinstadtConfig } from '../configs/meinstadt.config';
 import { Exporter } from '../interfaces/exporter.interface';
 
+/**
+ * ExportType.MEINSTADT (ADV-325/326). Wires the Cronicle/Nest services into MeinstadtFeedRun, which
+ * holds the logic. The output directory is no longer emptied: the new JSON/ZIP replace the old ones
+ * only after the fail-closed guard passed.
+ */
 @Injectable()
 export class MeinstadtExporter implements Exporter {
   constructor(
@@ -18,38 +25,52 @@ export class MeinstadtExporter implements Exporter {
     private configService: ConfigService,
     private rulesService: RulesService,
     private loaderService: LoaderService,
+    private imagesService: ImagesService,
     private moduleRef: ModuleRef,
   ) {}
 
   async export(): Promise<void> {
-    const [fileJson, fileGZ] = this.configService.config.outputFiles;
-    await CronicleUtils.ensureDir(this.configService.config.pathesConfig.localConvertedDirectory);
-    await CronicleUtils.emptyDir(this.configService.config.pathesConfig.localConvertedDirectory);
+    const config = this.configService.config as MeinstadtConfig;
+    const [jsonFile, zipFile] = config.outputFiles;
+    const validator = new ImageUrlValidator({ concurrency: config.imageConcurrency });
+    const transformer = await this.moduleRef.create(MeinstadtTransformer);
 
-    const meinstadtJsonBuilder = new MeinstadtJsonBuilder(fileJson);
-    await meinstadtJsonBuilder.buildStart();
+    const run = new MeinstadtFeedRun(
+      {
+        forEachChunk: fn => this.loaderService.process((chunk: FsChunkInterface) => fn(chunk.data as MeinstadtSourceCar[])),
+        filterCar: source => this.carService.filterCar(source, this.rulesService.rules),
+        resolveImages: async ({ car, images }) => toMeinstadtImages(
+          await resolveOpenAiImageFields(this.imagesService.getCleanImages(car._id, images), validator),
+          config.maxImages,
+        ),
+        imageStats: () => validator.stats,
+        equipment: car => transformer.getDescription(car),
+        zip: zipSingleFile,
+        guard: new FeedGuard(config.feedGuard),
+      },
+      {
+        runId: config.runId,
+        dryRun: config.dryRun,
+        cpc: config.cpc,
+        domain: config.domain,
+        sourceDirectory: config.pathesConfig.localDirectory,
+        sourceBaseFileName: config.pathesConfig.baseFileName,
+        jsonFile,
+        zipFile,
+        stateDir: config.stateDir,
+      },
+    );
 
-    const meinstadtTransformer = await this.moduleRef.create(MeinstadtTransformer);
-
-    let firstCar = true;
-    await this.loaderService.process(async (chunk: FsChunkInterface) => {
-      chunk.data = chunk.data.filter(e => this.carService.filterCar(e, this.rulesService.rules));
-
-      for (const data of chunk.data) {
-        // console.time(`Transform ${data.car._id}`);
-        const car = await meinstadtTransformer.transform(data);
-        // console.timeEnd(`Transform ${data.car._id}`);
-        await meinstadtJsonBuilder.addItem(car as MeinstadtJsonItem, firstCar);
-        this.carService.counter.countCar(data.images);
-
-        if (firstCar) {
-          firstCar = false;
-        }
+    try {
+      const report = await run.run();
+      if (report.stale) {
+        console.log(`meinestadt feed STALE: last good file ${report.lastGoodAgeHours?.toFixed(1)} h old`);
       }
-    });
-
-    await meinstadtJsonBuilder.buildEnd();
-    await Zipper.zip({ dest: fileGZ, fileList: [fileJson] });
-    console.log(this.carService.counter.getCountedCars());
+    } catch (error) {
+      // main.ts would report a rejected run as {"complete":1,"code":0}; fail the job so the chained
+      // upload step does not run (report + lock already handled by the run).
+      LoggerService.exitError(`meinestadt feed not published: ${error?.message ?? error}`);
+      process.exit(1);
+    }
   }
 }

package/src/formats/autouncle-json.builder.ts

@@ -6,11 +6,9 @@ export class AutouncleJsonBuilder extends XMLBuilderBase {
     await this.write('{"ads":[');
   }
 
+  // firstSym: the first item goes without a leading comma (it was written twice before)
   async addItem(car: AutouncleJsonItem, firstSym?: boolean): Promise<void> {
-    if (firstSym) {
-      await this.write(`${JSON.stringify(car)}`);
-    }
-    await this.write(`,${JSON.stringify(car)}`);
+    await this.write(`${firstSym ? '' : ','}${JSON.stringify(car)}`);
   }
 
   async buildEnd(): Promise<void> {

package/src/interfaces/export-item.interface.ts

@@ -67,23 +67,27 @@ export interface OoyyoXmlItem extends FbXmlItem {
   mileage: string;
 }
 
+// Keys and order as the meinestadt exporter emits them (see docs/meinestadt/AUDIT.md §3).
 export interface MeinstadtJsonItem {
   id: string;
   make: string;
   model: string;
-  cpc: string;
+  // configured tariff; null only in dry-run without one
+  cpc: string | null;
   listingUrl: string;
   title: string;
-  accidentFree: boolean;
+  // null = unknown, never "accident-free"
+  accidentFree: boolean | null;
   mileage: number;
-  initialRegistration: string;
-  offerCreationDate: string;
+  // Unix seconds, null when missing/invalid
+  initialRegistration: number | null;
+  offerCreationDate: number | null;
   numberOfDoors: number;
   numberOfSeats: number;
   numberOfPreviousOwners: number;
   price: number;
-  powerPS: string;
-  powerKS: string;
+  // PS
+  power: number;
   co2Emissions: number;
   fuelConsumptionCombined: number;
   equipment: string;
@@ -92,14 +96,13 @@ export interface MeinstadtJsonItem {
   emissionClass: string;
   emissionSticker: string;
   fuelType: string;
-  transmissionType: string;
-  sellerType: string;
-  usageState: string;
-  imagesCount: number;
-  images: string;
-  power: number;
   'transmissionType/transmission': string;
+  // = images.length
+  imagesCount: number;
   'customerType/sellerType': string;
+  usageState: string;
+  // validated public image URLs, hero first
+  images: string[];
 }
 
 export interface AutouncleJsonItem {

package/src/interfaces/openai-ads.interface.ts

@@ -53,6 +53,8 @@ export enum OpenAiAdsExclusion {
   dealerInactive = 'dealer_inactive',
   dealerUnknown = 'dealer_unknown',
   noImage = 'no_image',
+  // finance wording left after stripping (rates, Zins, Leasing, mtl., …) — ADV-335/336 launch gate
+  financeClaim = 'finance_claim',
 }
 
 // Why an item is sent as out_of_stock.

package/src/interfaces/params.interface.ts

@@ -38,6 +38,16 @@ export interface Params {
   feedGuardMaxStaleHours?: string;
   // "true" for ONE run after a real stock drop the guard blocked
   feedGuardAcceptDrop?: string;
+  // meinestadt feed only (ADV-325/326), Cronicle text params; see configs/meinstadt.config.ts.
+  // Live output needs meinstadtDryRun=false AND a cpc explicitly.
+  meinstadtDryRun?: string;
+  meinstadtImageConcurrency?: string;
+  meinstadtMaxImages?: string;
+  // AutoUncle feed only (ADV-322/323), Cronicle text params; see configs/autouncle.config.ts.
+  // Live output needs autouncleDryRun=false explicitly.
+  autouncleDryRun?: string;
+  autouncleImageConcurrency?: string;
+  autouncleMaxImages?: string;
 }
 
 // Parsed from feedItemsBq* by GoogleConfig.

package/src/services/autouncle-feed-run.ts

@@ -0,0 +1,197 @@
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { ImboImageResponseInterface } from '@bytebrand/chunkable';
+import { DataSchemes } from '@bytebrand/car-schema';
+
+import { AutouncleJsonBuilder } from '../formats/autouncle-json.builder';
+import { AutouncleAddress, AutouncleExclusion, getAutouncleExclusion, mapAutouncleItem } from '../transformers/autouncle.transformer';
+import { FeedGuard, FeedGuardError, LastGood, inspectSourceSnapshot } from './feed-guard';
+
+export interface AutouncleSourceCar {
+  car: DataSchemes.Car;
+  images: ImboImageResponseInterface[];
+}
+
+// Everything the run needs from the outside world — the Nest exporter wires the real services,
+// tests pass fakes.
+export interface AutouncleRunDeps {
+  // iterates the base export snapshot chunk by chunk (LoaderService.process)
+  forEachChunk: (fn: (cars: AutouncleSourceCar[]) => Promise<void>) => Promise<unknown>;
+  // existing shared partner filter (images count, Cronicle rules incl. the dealer allow-list)
+  filterCar: (source: AutouncleSourceCar) => boolean;
+  // dealer address of the car's owner; null = owner is not a dealer / not found
+  dealerAddress: (ownerId: string) => Promise<AutouncleAddress | null>;
+  // final validated image URLs for the car, hero first; [] = no usable image
+  resolveImages: (source: AutouncleSourceCar) => Promise<string[]>;
+  imageStats: () => Record<string, number>;
+  translate: (key: string) => string;
+  guard: FeedGuard;
+}
+
+export interface AutouncleRunOptions {
+  runId?: string;
+  dryRun: boolean;
+  domain: string;
+  sourceDirectory: string;
+  sourceBaseFileName: string;
+  jsonFile: string;
+  stateDir: string;
+  now?: () => Date;
+}
+
+export interface AutouncleRunReport {
+  runId?: string;
+  mode: 'dry-run' | 'live';
+  startedAt: string;
+  finishedAt?: string;
+  status: 'published' | 'blocked' | 'failed';
+  guard?: { code: string; message: string };
+  error?: string;
+  jsonFile: string;
+  source: { files: number; newestChunkAt: string | null; cars: number };
+  items: number;
+  dealers: number;
+  excluded: Record<string, number>;
+  imagesPerItem: { min: number | null; max: number | null; total: number };
+  images: Record<string, number>;
+  lastGood: LastGood | null;
+  lastGoodAgeHours: number | null;
+  stale: boolean;
+}
+
+const increment = (counter: Record<string, number>, key: string) => {
+  counter[key] = (counter[key] ?? 0) + 1;
+};
+
+/**
+ * One AutoUncle feed run (ADV-322/323): source check -> map + validated images -> temp JSON ->
+ * count check -> atomic publish -> report. Replaces the old flow that emptied the output directory
+ * first, so an outage published an empty or partial file. Nothing outside the output directory and
+ * `stateDir` is written; a blocked run leaves the last good JSON in place.
+ */
+export class AutouncleFeedRun {
+  constructor(private readonly deps: AutouncleRunDeps, private readonly options: AutouncleRunOptions) { }
+
+  private now(): Date {
+    return this.options.now ? this.options.now() : new Date();
+  }
+
+  async run(): Promise<AutouncleRunReport> {
+    const { guard } = this.deps;
+    const { jsonFile, runId, dryRun } = this.options;
+    const startedAt = this.now();
+    const lastGood = await guard.readLastGood();
+    const report: AutouncleRunReport = {
+      runId,
+      mode: dryRun ? 'dry-run' : 'live',
+      startedAt: startedAt.toISOString(),
+      status: 'failed',
+      jsonFile,
+      source: { files: 0, newestChunkAt: null, cars: 0 },
+      items: 0,
+      dealers: 0,
+      excluded: {},
+      imagesPerItem: { min: null, max: null, total: 0 },
+      images: {},
+      lastGood,
+      lastGoodAgeHours: guard.staleHours(lastGood, startedAt),
+      stale: guard.isStale(lastGood, startedAt),
+    };
+
+    await guard.acquireLock(runId ?? 'local', startedAt);
+    const tmpFile = `${jsonFile}.tmp`;
+    try {
+      const snapshot = await inspectSourceSnapshot(this.options.sourceDirectory, this.options.sourceBaseFileName);
+      report.source.files = snapshot.files;
+      report.source.newestChunkAt = snapshot.newestMtime?.toISOString() ?? null;
+      guard.checkSource(snapshot, startedAt);
+
+      await fs.mkdir(dirname(jsonFile), { recursive: true });
+      // the builder appends — never onto a leftover temp file
+      await fs.rm(tmpFile, { force: true });
+      const builder = new AutouncleJsonBuilder(tmpFile);
+      await builder.buildStart();
+
+      const seen = new Set<string>();
+      const dealers = new Set<string>();
+      let first = true;
+      await this.deps.forEachChunk(async (cars) => {
+        for (const source of cars) {
+          report.source.cars += 1;
+          const id = String(source?.car?._id ?? '');
+          if (id && seen.has(id)) {
+            increment(report.excluded, AutouncleExclusion.duplicateId);
+            continue;
+          }
+          seen.add(id);
+          if (!this.deps.filterCar(source)) {
+            increment(report.excluded, AutouncleExclusion.filtered);
+            continue;
+          }
+          // cheap checks first: no image probe for a car that is excluded anyway
+          const excluded = getAutouncleExclusion(source.car);
+          if (excluded) {
+            increment(report.excluded, excluded);
+            continue;
+          }
+          const ownerId = String(source.car.metaData.ownerId).trim();
+          const address = await this.deps.dealerAddress(ownerId);
+          if (!address) {
+            increment(report.excluded, AutouncleExclusion.noDealer);
+            continue;
+          }
+          const images = await this.deps.resolveImages(source);
+          const mapped = mapAutouncleItem(source.car, { domain: this.options.domain, address, images, translate: this.deps.translate });
+          if (mapped.ok === false) {
+            increment(report.excluded, mapped.reason);
+            continue;
+          }
+          await builder.addItem(mapped.item, first);
+          first = false;
+          dealers.add(ownerId);
+          this.count(report, mapped.item.images.length);
+        }
+      });
+      await builder.buildEnd();
+      report.dealers = dealers.size;
+      report.images = this.deps.imageStats();
+
+      const counts = { sourceItems: report.source.cars, publishedItems: report.items };
+      guard.checkCounts(counts, lastGood);
+
+      report.lastGood = await guard.publish(tmpFile, jsonFile, counts, this.now(), runId);
+      report.status = 'published';
+      report.lastGoodAgeHours = 0;
+      report.stale = false;
+      return report;
+    } catch (error) {
+      if (error instanceof FeedGuardError) {
+        report.status = 'blocked';
+        report.guard = { code: error.code, message: error.message };
+      } else {
+        report.error = error?.message ?? String(error);
+      }
+      // keep the rejected file for inspection; the published file stays untouched
+      await fs.rename(tmpFile, `${jsonFile}.rejected`).catch(() => undefined);
+      throw error;
+    } finally {
+      await this.writeReport(report);
+      await guard.releaseLock();
+    }
+  }
+
+  private count(report: AutouncleRunReport, images: number): void {
+    report.items += 1;
+    const stats = report.imagesPerItem;
+    stats.min = stats.min === null ? images : Math.min(stats.min, images);
+    stats.max = stats.max === null ? images : Math.max(stats.max, images);
+    stats.total += images;
+  }
+
+  private async writeReport(report: AutouncleRunReport): Promise<void> {
+    report.finishedAt = this.now().toISOString();
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(join(this.options.stateDir, 'last-run-report.json'), JSON.stringify(report, null, 2), 'utf8');
+    console.log(`autouncle feed report: ${JSON.stringify(report)}`);
+  }
+}