# VImplement CSV Automation Kit 0.1.0

Run repeatable CSV comparisons from an existing Node.js workflow. This dependency-free kit compares explicitly mapped record IDs, amounts and currencies using the same comparison engine as CSV Compare. It runs locally, makes no network calls, and needs no AI API key, subscription or package installation.

Requires Node.js 20 or later and a local filesystem supporting hard links (for example NTFS, APFS or ext4). Network shares, cloud-synced folders, symbolic links, junctions and filesystems without hard-link support are not supported. Use a stable local working directory owned by the operator.

## Try the included synthetic example

Extract the whole ZIP, open your own terminal in that folder, then run:

    node run.cjs --left examples/left.csv --right examples/right.csv --profile examples/profile.json --out-dir example-output

The output parent must already exist; example-output must not exist. The expected result is **8 left records, 7 right records, 2 matched pairs and 6 review entries**. The output contains report.csv and summary.json. Included examples/expected-report.csv is a known expected result, not your output.

A second run with the same output directory deliberately fails. Choose a new directory for each run. Do not delete previous reports automatically unless your own retention policy calls for it.

## Use your own exports

Create UTF-8 CSV or TSV files. Export Excel worksheets to CSV first; XLS/XLSX workbooks are not supported. Copy examples/profile.json and explicitly select each source's delimiter, decimal separator and column names. The profile schema is shared with CSV Compare's exported mapping profiles.

- Delimiter: comma, semicolon, or tab (JSON "\t").
- Decimal separator: "." or ",". Thousands grouping is not supported.
- mapping.key: required, exact header name.
- mapping.amount and mapping.currency: exact header names, or an empty string to leave that field off on both sources.
- A different column must be used for each mapped field.
- Keys are trimmed and case sensitive. Currency values are uppercased; their three-letter format is checked, not membership in an ISO registry.
- Amounts use exact normalized decimals: up to 18 whole and 6 fractional digits, no floating-point tolerance.
- No mappings, periods, filters or financial meaning are inferred.

    node run.cjs --left exports/source.csv --right exports/target.csv --profile mapping.json --out-dir results/run-001 --fail-on-diff

Create the results parent directory yourself first. Quote paths with spaces when entering them into your terminal. In programmatic integrations, pass a fixed executable and an argument array with shell disabled; never interpolate untrusted file names into a shell command.

## Outputs and exit codes

report.csv contains every comparison entry, including matches. It includes mapped keys, amounts, currencies and source row references. Treat it as confidential source-derived data. Spreadsheet formula-like values are prefixed with an apostrophe for safer CSV opening; a leading apostrophe on a negative amount is intentional and does not change the comparison.

summary.json contains counts, status counts, field names ("key", "amount", "currency"), source byte counts and SHA256 fingerprints, and the profile fingerprint. It contains no source rows, source paths, customer values or actual header mappings. Its presence with complete=true is the completed-run marker.

Output files are first fully written and synced in a temporary sibling directory. The destination is reserved exclusively; each final filename is published atomically without replacement using a hard link. summary.json is published last. A process crash can leave a directory with report.csv but no summary.json; treat that run as incomplete and retry into a new directory. This is not a multi-file transactional database or a security boundary against another process modifying the working filesystem.

- Exit 0: comparison completed. Review entries can still exist unless --fail-on-diff was used.
- Exit 2: comparison completed with review entries and --fail-on-diff was supplied. Both output files are still produced.
- Exit 1: invalid input, profile, arguments or output. Read stderr. Existing files are not intentionally replaced.
- --help and --version work alone.

Invalid amounts, missing keys and duplicate keys are review entries, not malformed-file failures. They quarantine affected keys according to the engine. Malformed CSV, unavailable headers, invalid profiles and oversized files are exit-1 failures.

## Scope and limits

Up to 10,000 data rows and 2 MiB (2,097,152 bytes) per source; up to 100 columns. Mapping profiles are at most 16,384 bytes. Blank physical lines are ignored. Unmapped columns are not compared.

No database, shared workspace, background service, automatic export collection, notifications, store account, hosted runner, custom connectors, payment collection or AI inference is included. You control scheduling and review. Differences do not establish financial loss, missing payments or accounting conclusions.

The kit does not install an autostart or scheduled task. For unattended Windows use, configure your existing supervisor to launch Node with a hidden process window and shell disabled, using a fresh output directory per run. Run on the machine that holds the exports. Do not use a visible-console launcher for scheduled automation.

This is a versioned software download licensed to one named operator. There is no recurring subscription or promise of indefinite updates, custom integration or a response-time SLA. Read LICENSE.txt before use. Product support and refund requests: bergvictor1999@outlook.com, including your order reference. Mandatory statutory rights are unaffected.

## Verify your download

MANIFEST.json lists SHA256 hashes for every other package member. It can be compared using a trusted SHA256 tool. The manifest itself is not a digital signature; obtain the ZIP fingerprint from your trusted purchase/delivery record.