# GisConverter ConsoleApp

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

This README documents usage, examples, debug helpers, exit codes, logging, test guidance and notes for maintainers.

---

## Overview

The ConsoleApp exposes a single command:

- `gis_convert <input> <format> <output> <temp> [Log <log_file_path> [level]]`

Behavior highlights:

- Attempts to detect input format and select an appropriate converter.
- Validates arguments and input paths.
- Initializes optional file logging when requested.
- Delegates conversion work to `GisConverter.Lib` converters via `ConverterFactory`.
- Exposes `Program.Run(string[] args)` that returns an integer exit code (used by tests); the app avoids calling `Environment.Exit` so test runners remain alive.

---

## 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> [level]]

Arguments
- `<gis_input_file_path>` — single file (e.g., `.csv`, `.gml`) or archive containing the format's files (e.g., shapefile `.7z`/`.zip`).
- `<gis_target_format_option>` — canonical option (case-insensitive), e.g., `Shapefile`, `GeoJson`, `Csv`, `Gml`.
- `<output_folder_path>` — destination folder for generated files.
- `<temp_folder_path>` — temp working folder for extraction/intermediates. Converters create it if missing.
- Optional `Log <log_file_path> [level]` — enable file logging. Levels: `ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF`.

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

Notes
- Quote paths with spaces. In DEBUG builds the CLI includes tolerant repair logic that can join adjacent tokens into one path.
- Converters expect certain inputs for some formats (e.g., Shapefile archives must contain `.shp`, `.shx`, `.dbf`).

---

## Supported target options

Canonical options are registered in `ConverterFactory`. Typical names:
Shapefile, GeoJson, GeoJsonSeq, EsriJson, Kml, Kmz, Gml, Csv, GeoPackage, Osm, Gpx, MapInfoTab, MapInfoInterchange, TopoJson, Gdb.

See `ConverterFactory` for the definitive list.

---

## Exit codes

`Program.Run` returns:
- `0` — Success
- `1` — App error (invalid args, unknown command, usage shown, detection failure)
- `2` — Conversion failed (converter returned failure or null)
- `3` — Unexpected exception

Automation should inspect the exit code and capture console output for diagnostics.

---

## Logging

Enable logging with `Log <path> [level]`.

- Initialization is best-effort; failures do not abort conversion and are reported to stderr.
- Example:
  `gis_convert input.7z Shapefile outDir tempDir Log "C:\logs\convert.txt" DEBUG`
- If logging cannot be initialized the app writes a concise warning to `Console.Error`.

---

## Temp folder and cleanup

- `temp` is used for extraction and intermediates.
- Converters create and clean what they create. If you pass an existing folder they avoid deleting it unless created by the run.

---

## Detection vs filesystem validation (important for tests)

- The CLI attempts converter detection (resolve converter from input token) before enforcing a filesystem existence check in some code paths.
  - Rationale: developer convenience (repair unquoted paths) and richer diagnostics when token parsing fails.
- Testing guidance:
  - Tests sometimes use synthetic/non-existent input paths to validate parsing and detection. Those tests may observe detection messages (e.g., "Unable to auto-detect converter from input", "Detector reason") rather than an immediate "input path not found".
  - Keep assertions tolerant for negative flows — accept either detection/usage output OR an input-not-found diagnostic.
  - Example assertion pattern:
    ```csharp
    var combined = stdout + "\n" + stderr;
    Assert.True(
      combined.Contains("Unable to auto-detect converter from input", StringComparison.OrdinalIgnoreCase)
      || combined.Contains("Detector reason", StringComparison.OrdinalIgnoreCase)
      || combined.Contains("Usage", StringComparison.OrdinalIgnoreCase)
      || combined.Contains("input path not found", StringComparison.OrdinalIgnoreCase),
      $"Unexpected CLI output:\n{combined}");
    ```
  - If you require deterministic path-existence behavior in a test, create or remove filesystem state explicitly before calling `Program.Run`.

---

## Automated tests & test guidance

- Tests invoke `Program.Run(string[] args)` directly (no separate process). Ensure ConsoleApp is built when running tests that probe its assembly.
- Tests capture `Console.Out`/`Console.Error` via `StringWriter` for assertions.
- Use the `Logging` test collection to serialize tests that manipulate global logging state or shared log files.
- Prefer case-insensitive substring assertions to reduce brittleness.

---

## Debugging (Visual Studio)

To set a debug scenario without typing long args:
1. Right-click the ConsoleApp project → __Properties__ → __Debug__.
2. Add environment variable `GISCONVERTER_DEBUG_TARGET` with a scenario (e.g., `Shapefile1`, `Csv1`).
3. Start debugging — debug defaults apply only in Debug builds.

---

## Implementation notes

- The ConsoleApp:
  - Applies Aspose license early via `AsposeLicenseManager.ApplyLicense()` (fail-fast with friendly message when required).
  - Parses args, configures logging (via `GetOptionalLogArguments` / `SetLogger`), detects converter using `ConverterFactoryInputExtensions.TryCreateForInput`, and invokes the resolved converter.
  - Writes concise, human-readable diagnostics to stdout/stderr. Avoid changing message tokens lightly — tests rely on them.

- Exposes `Run(string[] args)` that returns exit codes and avoids terminating the process so tests remain stable.

---

## Troubleshooting

- Conversion failure: inspect stdout/stderr and the log file if enabled.
- Missing `Program` type in tests: ensure ConsoleApp project is built and the binary is present in probed output directories.
- Sample files missing: verify `<CopyToOutputDirectory>PreserveNewest` is set in test projects.
- Aspose license: provision via CI secrets or local environment; `AsposeLicenseManager.ApplyLicense()` logs diagnostics and should be checked by callers.

---

## Contributing & contact

- Open issues for defects, missing sample data or flaky tests. Include captured stdout/stderr and `TestLogger` output when possible.
- Add small representative sample artifacts under `TestsApp/TestData` and update `IntegrationTestConstants` when adding scenarios.

---

## License & attribution

The project follows the repository license. Third‑party components (e.g., Aspose) have their own licenses — consult vendor documentation.

---