# GitConverter ConsoleApp

Lightweight command-line front-end that dispatches GIS conversion requests to the library converters in this repository.

## Overview
The ConsoleApp exposes a single command, `gis_convert`, which accepts a GIS input artifact (single file or archive), a canonical target format option, and output/temp paths. The CLI validates paths, invokes the appropriate converter and prints a concise result to console. Optional file logging can be enabled.

This README documents usage, examples, debug helpers and exit codes.

## Usage
Syntax:
GISConverter.Cli.exe gis_convert <gis_input_file_path> <gis_target_format_option> <output_folder_path> <temp_folder_path> [Log <log_file_path>]

Parameters
- `<gis_input_file_path>` — path to a single GIS file (e.g., .csv, .gml) or an archive containing the format's required files (e.g., shapefile .7z/.zip containing .shp/.shx/.dbf).
- `<gis_target_format_option>` — canonical option string (case-insensitive) such as `Shapefile`, `GeoJson`, `Csv`, `Gml`, etc.
- `<output_folder_path>` — destination directory where the converter will write its output file(s). The converter creates files inside this folder.
- `<temp_folder_path>` — temporary working folder for extraction and intermediate files. Converters create it if missing and attempt best-effort cleanup of what they created.
- Optional `Log <log_file_path>` — enable file logging to the given path. Pass the word `Log` followed by the path.

Examples
- Convert a CSV file to GeoJSON:
  `GISConverter.Cli.exe gis_convert "C:\data\features.csv" GeoJson "C:\out" "C:\temp" Log "C:\logs\run.log"`
- Convert a shapefile archive to GeoPackage:
  `GISConverter.Cli.exe gis_convert "C:\data\shapefile.7z" GeoPackage "C:\out" "C:\temp"`

Notes
- If the input path contains spaces, quote it. In Debug builds the CLI contains tolerant logic that can repair some unquoted inputs for developer convenience by detecting the target token.
- The converters expect specific inputs for some formats:
  - Shapefile: archive containing `.shp`, `.shx`, `.dbf`.
  - Csv/Gml/GeoJson: single file or an archive containing the file.

## Supported Target Options
Supported canonical options are registered in the library factory. Typical names:
- Shapefile
- GeoJson
- GeoJsonSeq
- EsriJson
- Kml / Kmz
- Gml
- Csv
- GeoPackage
- Osm, Gpx, MapInfoTab, MapInfoInterchange, TopoJson, Gdb

For the definitive list see `ConverterFactory` in the library.

## Exit Codes
Program.Run returns an integer exit code:
- `0` — Success
- `1` — App error (invalid args, unknown command, usage displayed)
- `2` — Conversion failed (converter returned Failure)
- `3` — Unexpected exception

Scripts should check the exit code and capture console output for diagnostics.

## Logging
To enable file logging pass `Log <log_file_path>`. The application will attempt to initialize logging; failures to configure logging are non-fatal and reported to stderr.

Example:
gis_convert input.7z Shapefile outDir tempDir Log "C:\logs\convert.txt"

Logging is best-effort — invalid or inaccessible paths will disable logging and print a warning.

## Temp folder and cleanup behavior
- `temp_folder_path` is used for archive extraction and intermediate files.
- Converters create the folder if it does not exist. They attempt to clean up files and folders they created or extracted. If the caller supplies an existing folder, the converters avoid deleting it unless they created it during the run.

## Debugging (Visual Studio)
When running under Visual Studio you can set a debug scenario without typing full CLI arguments:
1. Right-click the ConsoleApp project → __Properties__ → __Debug__.
2. Add an environment variable: `GITCONVERTER_DEBUG_TARGET` with a predefined scenario name (examples: `Shapefile1`, `Csv1`, `Gml1`).
3. Start debugging — the project will use the configured debug args only in Debug builds.

This helper is for developer convenience and does not affect Release builds or CI.

## Automated tests
Unit and integration tests in the repository invoke the console entry point via the public `Program.Run(string[] args)` method rather than starting a new process. Tests therefore rely on `Program.Run` returning the appropriate exit codes and not calling `Environment.Exit` which would terminate the test process.

Typical expectations used by tests:
- Invoking the CLI with no arguments should print usage/help and return exit code `1` (application error).
- Unknown or invalid target options should result in usage/diagnostic output and return exit code `1`.

When changing CLI behavior, update tests to match the new contract or adjust the implementation so tests remain deterministic.

## Troubleshooting
- If conversion fails, check stdout/stderr and the optional log file for details.
- Ensure archives contain required files (e.g., shapefile components).
- Aspose license: production builds should embed or supply the Aspose license; converters return a friendly failure if the license is missing.

## Running Integration Tests
- Place small sample files under `TestsApp/TestData\<format>` (e.g., `TestData\Shapefile`, `TestData\Csv`, `TestData\Gml`) and set `CopyToOutputDirectory=PreserveNewest` in the test project so samples are available at runtime.
- Integration tests are defensive and skip when samples are absent.

## Implementation notes
- The ConsoleApp delegates format resolution to `ConverterFactory` and conversion work to the library converters (CsvConverter, GmlConverter, ShapefileConverter, etc.).
- The entry point exposes a public `Run(string[] args)` that returns an exit code without calling `Environment.Exit` (used by integration tests via reflection).

## Contact / Contributing
- Open issues for defects or missing sample data.
- Add small representative test samples under `TestsApp/TestData` and update `IntegrationTestConstants` when adding scenarios