# xls-to-csv

Convert Excel workbooks (`.xlsx` / `.xls` / `.xlsm` / `.xlsb`) to CSV, one CSV
per worksheet. Optionally move each source into a "processed" folder after it
converts successfully.

Uses headless Excel (COM), so it handles modern OOXML workbooks and legacy
binary `.xls` (OLE2) alike, including files that are secretly legacy `.xls`
behind a `.xlsx` extension.

## Quick start

Batch a folder (robust: per-file timeout, safe resume, move-on-success):

```powershell
python "C:\Users\<you>\.copilot\m-skills\xls-to-csv\batch.py" `
  --input-dir     "C:\path\Raw" `
  --out           "C:\path\Output" `
  --processed-dir "C:\path\Raw\Processed" `
  --log           "C:\path\batch.log" `
  --result        "C:\path\summary.json" `
  --timeout 300 --skip-existing
```

One or a few files:

```powershell
python "C:\Users\<you>\.copilot\m-skills\xls-to-csv\convert.py" `
  --input "C:\path\a.xlsx" --out "C:\path\Output" [--processed-dir "C:\path\Processed"]
```

## Output naming

- Single-sheet workbook -> `<basename>.csv`
- Multi-sheet workbook -> `<basename> - <SheetName>.csv` per sheet

## Options

| Flag              | Purpose                                                       |
| ----------------- | ------------------------------------------------------------- |
| `--input`         | A source workbook. Repeat for multiple (convert.py).          |
| `--input-dir`     | Convert every workbook in a folder (non-recursive).           |
| `--out`           | Output directory for `.csv` files.                            |
| `--processed-dir` | Move each source here after a successful conversion.          |
| `--skip-existing` | Skip a workbook whose primary `.csv` already exists.          |
| `--timeout`       | (batch.py) Per-file timeout in seconds, default 300.          |

## Behavior

- UTF-8 CSV (`xlCSVUTF8`), fallback to local-encoding CSV on older Excel.
- Each worksheet exported separately, so multi-sheet workbooks convert fully.
- Move happens only on success; failed/timed-out files stay in place.
- OneDrive cloud files are hydrated via a temp copy before conversion.
- A workbook that hangs Excel is isolated and skipped; only that spawned Excel
  instance is killed.

## Requirements

Windows + Microsoft Excel (headless COM) + Python 3.12 with `pywin32`.

See `SKILL.md` for the full agent workflow, QA guidance, and edge cases.